Outbound Webhooks

Sakneen outbound webhooks notify your server when subscribed resources change. They are designed for server-to-server integrations that need near-real-time Client and Wallet data without polling Sakneen.

How it works

1. An organization administrator creates an Application in the Sakneen Developer Console.
2. The administrator adds one or more Event destinations to the application.
3. Each destination specifies a public HTTPS endpoint and the events it wants to receive.
4. When a subscribed event occurs, Sakneen sends a signed JSON request to every active matching destination.
5. Your endpoint verifies the signature, stores the event idempotently, and returns a 2xx response.

Sakneen resource change
        ↓
Immutable event
        ↓
Active subscribed destinations
        ↓
Signed HTTPS webhook
        ↓
Your server

Each destination is independent. One application can have multiple destinations, and each destination can subscribe to a different set of events.

Available event families

Resource	Events
Client	client.created, client.updated
Wallet	wallet.created, wallet.updated, wallet.archived
Wallet installment	wallet_installment.created, wallet_installment.updated, wallet_installment.superseded
Wallet cheque	wallet_cheque.created, wallet_cheque.updated
Wallet collection	wallet_collection.created, wallet_collection.updated, wallet_collection.reversed

All currently published events use event contract version 1.

Client deletion

client.deleted is reserved in the Developer Console event catalog, but Sakneen does not currently emit it. Do not depend on this event until this documentation marks it as available.

Webhooks and API keys are different

Sakneen API keys authenticate requests that your system sends to Sakneen. Outbound webhooks travel in the opposite direction and do not include your API key.

Sakneen authenticates each outbound webhook with a destination-specific signing secret and the X-Sakneen-Signature header. See Verify webhook signatures.

Delivery model

Webhook delivery is at least once. A webhook can be sent more than once when a response is lost or a retryable failure occurs. Your receiver must use eventId as its idempotency key.

Sakneen does not guarantee global delivery order. Use resource.id together with resource.version when you need to reject an older state for the same resource.

Events begin after an active destination subscribes. Historical Client or Wallet changes are not backfilled.

Next steps

1. Configure an event destination
2. Understand the event envelope
3. Verify webhook signatures
4. Review the Client events and Wallet events
5. Implement the delivery and retry recommendations