Process webhooks securely

Webhooks deliver published events asynchronously. Register a public HTTPS endpoint and use the test delivery before monitoring an integration.

A successful AF-378 settings copy creates audit evidence, but no Partner API webhook event and no business envelope.

Verify HMAC

For HMAC delivery, the secret is returned once during registration. Save it immediately in a secret store. Calculate HMAC-SHA256 over x-akflow-timestamp, a period and the unmodified HTTP body; compare it with x-akflow-signature in constant time.

signed_payload = x-akflow-timestamp + "." + raw_request_body
expected       = HMAC-SHA256(webhook_secret, signed_payload)

Verify before parsing or formatting JSON. Return a 2xx response promptly after successful acceptance, then process the event from your own queue.

Idempotency and failures

• De-duplicate deliveries using the stable event or idempotency identifier from the contract.
• Repeated delivery must have the same result and must not create a second business action.
• Return 2xx only after acceptance; timeouts and other statuses can be retried.
• Alert on persistent signature errors, backlog and repeated delivery failures.