Webhook Integration

Validate every callback with HMAC SHA-256, reject stale timestamps, and design idempotent consumers.

Headers

Header	Description
`X-Webhook-Signature`	HMAC SHA-256 digest (hex)
`X-Webhook-Timestamp`	Unix timestamp used in signature base string
`X-Request-Id`	Unique request correlation identifier

Signature Verification Example (PHP)

$payload = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '';
$provided = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $timestamp.'.'.$payload, $secret);

if (! hash_equals($expected, $provided)) {
    http_response_code(401);
    exit('invalid signature');
}

Delivery Rules

Respond with HTTP 2xx quickly after signature and timestamp validation.
Process the event asynchronously in your application worker.
Store event IDs to protect against duplicate callback retries.