Process webhooks securely

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

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.