Webhooks

Webhooks let your system react the moment something happens on the platform — a customer completes onboarding, a card is issued, a payment settles, or a balance changes. Instead of polling the API, Orenda pushes the event to you.

How it works

Orenda POSTs a signed JSON payload to a consumer URL you register for your program. To get started, contact the team to register your endpoint and receive your signing secret. Your program registers two consumer URLs — one for production and one for sandbox — and they must be unique. Each event is delivered to the matching endpoint based on the environment it originated in.

Common envelope

Every webhook delivery has the same top-level fields. The event type determines which additional object is included — for example, account events include an account object, card events include a card object, and so on.

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`
`CARD_AUTHORIZATION_REQUESTED`	A card authorisation needs a real-time approve/decline decision.	`cardAuthentication`
`CARD_AUTHORIZATION_INCREMENTAL`	An incremental authorisation is requested on an existing hold.	`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.

Card authorisation requests work differently. Most webhooks are fire-and-forget notifications — you receive them and acknowledge with a 2xx. The card authorisation request webhook is the exception: Orenda sends it and waits for your response to approve or decline the transaction in real time. It also uses a different signing format. Your program must be registered for this service — contact the team to enable it. See its reference page for details.

Verifying the signature

The signing method below applies to notification webhooks only. Card authorisation requests sign <timestamp>.<body> instead of the body alone, so you will need a separate verification path for those.

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"];

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

How it works

Common envelope

Events

Verifying the signature

Delivery behaviour

​How it works

​Common envelope

​Events

​Verifying the signature

​Delivery behaviour

How it works

Common envelope

Events

Verifying the signature

Delivery behaviour