Orenda notifies your backend of platform events by POSTing to webhook consumer URLs
registered for your program (contact the team to
register endpoints and receive your signing secret).
Each program can register one or more consumer URLs. A given event is delivered to
every consumer registered for that program whose sandbox flag matches the event’s
environment (a sandbox event is only sent to sandbox consumers, and vice versa).
Common envelope
Every webhook body shares the same envelope. Event-specific data hangs off a single
nested object (account, card, cardAuthentication, transaction, paymentRequest,
or the customer status fields).
| Field | Type | Notes |
|---|
eventId | string | Unique per delivery (UUID). Use it to de-duplicate. |
eventName | string | One of the events in the table below. |
timestamp | string | ISO 8601, when the event was generated. |
programId | string | Your program identifier. |
sandbox | boolean | true for sandbox traffic, false for production. |
customerId | string | The customer the event relates to. |
clientReference | string | Optional. Echoed back when one was set on the customer. |
Events
Each event has its own reference page with the exact payload it carries.
| Event | Fires when | Payload object |
|---|
CUSTOMER_STATUS_UPDATE | A customer’s onboarding/KYC status changes. | status fields |
ACCOUNT_STATUS_UPDATE | An account’s status changes. | account |
ACCOUNT_BALANCE_UPDATE | An account’s settled balance changes. | account |
NEW_CARD_ADDED | A new card is provisioned. | card |
CARD_STATUS_UPDATE | A card’s lifecycle status changes. | card |
CARD_AUTH_STATUS_UPDATE | A card authorisation / 3DS challenge is raised or resolved. | cardAuthentication |
TRANSACTION_INITIATED | A payment request is created. | paymentRequest |
TRANSACTION_CREATED | A ledger transaction is created. | transaction (id only) |
TRANSACTION_STATUS_CHANGED | A ledger transaction’s status changes. | transaction (id only) |
Payloads are thin by design. Transaction events carry only an identifier (e.g.
transactionId), not the full record — fetch the details through the API with your
operator credentials. Don’t expect the full objects older docs may have shown.
Verifying the signature
Every delivery is signed with HMAC-SHA256 over the JSON body (keys serialised in
sorted order), using your program’s signing secret. The signature arrives in the
Orenda-Payload-Signature header as a plain hex digest:
const crypto = require("crypto");
const expected = crypto
.createHmac("sha256", signingSecret)
.update(rawBody) // the raw request body, byte-for-byte
.digest("hex");
const ok = expected === req.headers["orenda-payload-signature"];
If you implemented against the old docs: the header is Orenda-Payload-Signature with a
bare hex digest — not x-orenda-signature and no sha256= prefix.
Delivery behaviour
Respond with any 2xx to acknowledge. There is no automatic retry on failure — a
delivery that fails (non-2xx, timeout, or connection error) is logged and dropped, not
re-queued. Design your handler to be reliable and idempotent (de-duplicate on eventId),
and reconcile via the API (e.g. search) if you suspect missed events. For
delivery investigations, contact the team.