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 thenotify-days-beforewindow of itsaccess-event.expirydate. Allows Controllers to prompt the customer to renew before their access lapses. Only fired for records whereaccess-event.expiryis non-null andaccess-event.stateisACTIVE. -
tenancy.change— fired when the register receives notification that a Change of Tenancy has been recorded against an MPxN that has one or moreACTIVEaccess 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-urlwith the event payload as the request body. - The callback endpoint must respond with HTTP
2xxwithin 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
undeliveredand the Data User is notified via the registeredalert-email. - The register signs each delivery with an HMAC-SHA256 signature over the
raw request body, using the
signing-secretreturned at registration. The signature is passed in theX-DAR-Signatureheader assha256=<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}.
Authorizations
JWT from GET /auth/token. Pass as Authorization: Bearer <token>. Expires after 7200s.
Body
HTTPS endpoint that will receive event POST requests. HTTP (non-TLS) URLs are rejected. The endpoint must return HTTP 2xx within 10 seconds.
"https://app.bright-energy.com/webhooks/dar"
Email address to notify if repeated delivery failures occur (after the final retry attempt). Should be a monitored operations mailbox.
"platform-ops@bright-energy.com"
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.
1 <= x <= 9030
Event types this subscription should receive. Defaults to all types if omitted.
1The event type delivered to the webhook callback URL.
consent.expiring— a consent-based access record is within the configurednotify-days-beforewindow of its expiry date.tenancy.change— a Change of Tenancy has been recorded against an MPxN that has one or moreACTIVEaccess 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 toREVOKEDstate before this event is fired. Data Users must update their own systems immediately on receipt.
consent.expiring, tenancy.change, consent.withdrawal Response
Webhook subscription created.
A registered webhook subscription as returned by the API.
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.
"whsec_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"