Webhooks

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.

One webhook is not a notification. Authorisation decisions asks you whether to approve a card authorisation and waits for your answer, on the card network’s clock. It has a different response contract and a different signing base from everything on this page.

Verifying the signature

This section covers the notification webhooks listed above. Authorisation decisions signs <timestamp>.<body> rather than the body alone — a verifier written for this section will reject every one of those deliveries.

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.

Get started

Oversight

Customer operations

Batch payments

Configuration

Common envelope

Events

Verifying the signature

Delivery behaviour

​Common envelope

​Events

​Verifying the signature

​Delivery behaviour

Common envelope

Events

Verifying the signature

Delivery behaviour