Webhooks

Register a Webhook Subscription

Registers an HTTPS callback URL to receive lifecycle event notifications dispatched by the register.

Two event types are delivered to the same callback URL, distinguished by the event-type field in the payload envelope:

consent.expiring — fired when a consent-based access record is within the notify-days-before window of its access-event.expiry date. Allows Controllers to prompt the customer to renew before their access lapses. Only fired for records where access-event.expiry is non-null and access-event.state is ACTIVE.
tenancy.change — fired when the register receives notification that a Change of Tenancy has been recorded against an MPxN that has one or more ACTIVE access records. Controllers should use this to halt data collection for the departing occupant and, if appropriate, initiate a fresh consent or access registration for the new occupant. The event carries only the MPxN and the effective date of the change — no new occupant PII is included.

Delivery semantics:

The register performs an HTTPS POST to the callback-url with the event payload as the request body.
The callback endpoint must respond with HTTP 2xx within 10 seconds.
On failure the register retries with exponential backoff: 1 min, 5 min, 30 min, 2 hr, 24 hr. After 5 failed attempts the event is marked undelivered and the Data User is notified via the registered alert-email.
The register signs each delivery with an HMAC-SHA256 signature over the raw request body, using the signing-secret returned at registration. The signature is passed in the X-DAR-Signature header as sha256=<hex-digest>. Receivers must verify this before processing.

Filtering: By default, subscriptions receive all event types for all access records registered under the authenticated Data User. Supply event-types to restrict to a specific subset.

Idempotency: Registering a second subscription with the same callback-url returns 409 Conflict. Update an existing subscription using PATCH /webhooks/{wid}.

POST

webhooks

curl --request POST \
  --url https://api.central.consent/v1/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "callback-url": "https://app.bright-energy.com/webhooks/dar",
  "alert-email": "platform-ops@bright-energy.com",
  "notify-days-before": 30,
  "event-types": [
    "consent.expiring",
    "tenancy.change"
  ]
}
'

{
  "response": {
    "resource": "/v1/access-records/ak_691df0c788ca043403b7fa90",
    "timestamp": "2026-03-11T12:00:00Z",
    "transaction-id": "tid_691df0c788ca043403b7fa90"
  },
  "webhook": {
    "wid": "wid_a1b2c3d4e5f6a1b2c3d4e5f6",
    "callback-url": "https://app.bright-energy.com/webhooks/dar",
    "alert-email": "platform-ops@bright-energy.com",
    "notify-days-before": 30,
    "event-types": [],
    "created-at": "2026-01-10T08:00:00Z",
    "active": true
  },
  "signing-secret": "whsec_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}

Authorizations

Authorization

string

header

required

JWT from GET /auth/token. Pass as Authorization: Bearer <token>. Expires after 7200s.

Body

application/json

callback-url

string<uri>

required

HTTPS endpoint that will receive event POST requests. HTTP (non-TLS) URLs are rejected. The endpoint must return HTTP 2xx within 10 seconds.

Example:

"https://app.bright-energy.com/webhooks/dar"

alert-email

string<email>

required

Email address to notify if repeated delivery failures occur (after the final retry attempt). Should be a monitored operations mailbox.

Example:

"platform-ops@bright-energy.com"

notify-days-before

integer

default:30

How many days before access-event.expiry the register should fire a consent.expiring event. Only applies to consent.expiring events. Default is 30 days if omitted.

Required range: 1 <= x <= 90

Example:

30

event-types

enum<string>[]

Event types this subscription should receive. Defaults to all types if omitted.

Minimum array length: 1

The event type delivered to the webhook callback URL.

consent.expiring — a consent-based access record is within the configured notify-days-before window of its expiry date.
tenancy.change — a Change of Tenancy has been recorded against an MPxN that has one or more ACTIVE access records registered under this Data User.
consent.withdrawal — a customer has withdrawn consent via the centralised Customer Consent Portal. The access record has already transitioned to REVOKED state before this event is fired. Data Users must update their own systems immediately on receipt.

Available options:

consent.expiring,

tenancy.change,

consent.withdrawal

Response

Webhook subscription created.

response

object

required

Show child attributes

webhook

object

required

A registered webhook subscription as returned by the API.

Show child attributes

signing-secret

string

HMAC-SHA256 signing secret for this subscription. Returned only on creation (POST) or when rotate-secret: true is supplied on update. Store securely — this value is not retrievable after the response is returned.

Example:

"whsec_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"

Last modified on March 25, 2026

Delete a Webhook SubscriptionPermanently removes a webhook subscription. In-flight deliveries already queued at the time of deletion will still be attempted.

curl --request POST \
  --url https://api.central.consent/v1/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "callback-url": "https://app.bright-energy.com/webhooks/dar",
  "alert-email": "platform-ops@bright-energy.com",
  "notify-days-before": 30,
  "event-types": [
    "consent.expiring",
    "tenancy.change"
  ]
}
'

{
  "response": {
    "resource": "/v1/access-records/ak_691df0c788ca043403b7fa90",
    "timestamp": "2026-03-11T12:00:00Z",
    "transaction-id": "tid_691df0c788ca043403b7fa90"
  },
  "webhook": {
    "wid": "wid_a1b2c3d4e5f6a1b2c3d4e5f6",
    "callback-url": "https://app.bright-energy.com/webhooks/dar",
    "alert-email": "platform-ops@bright-energy.com",
    "notify-days-before": 30,
    "event-types": [],
    "created-at": "2026-01-10T08:00:00Z",
    "active": true
  },
  "signing-secret": "whsec_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}

Documentation Index

Authorizations

Body

Response