Decision webhooks (Standard Webhooks)

The service tells your system about decisions with webhooks signed according to the Standard Webhooks specification.

Events

intent.approved, intent.denied, intent.expired, intent.cancelled. A decision is sent only once its receipt is signed.

The body carries identifiers, the state, the request digest and the signed receipt, never the field values:

{"type":"intent.approved","eventId":"…","intentId":"…","externalReference":"INV-42",
 "operationType":"invoice.pay","state":"approved","intentDigest":"…",
 "occurredAtEpochSeconds":1800000000,"receipt":{"status":"signed","payload":"…"}}

How do I verify?

Headers: webhook-id, webhook-timestamp (Unix seconds) and webhook-signature (v1,<base64 HMAC-SHA-256(secret, id "." timestamp "." body)>). The secret is the base64 after whsec_.

1. Read the body bytes before parsing the JSON.
2. Refuse a webhook-timestamp more than 5 minutes from your clock.
3. Compute the HMAC and compare it in constant time with each v1 signature.
4. Deduplicate on webhook-id: delivery is at least once.

The SDKs do this with verifyWebhook (TypeScript), verify_webhook (Python) and equivalents.

Delivery and retries

Answer with a 2xx within 10 seconds. Other answers are retried 12 times with exponential backoff (10 s doubling, up to one hour, with jitter) and then set aside.

Configuration

The administrator sets the https:// address on the machine client under «Manage» › «Third-party requests». The server delivers only to domains the operator allowed; without them the console says webhooks are unavailable.

Good practice

Treat the webhook as a hint: before running the operation, read GET /v1/intents/{intent_id} and verify the receipt.