Webhook design and async APIs
Sign events with HMAC-SHA256 (ADP-025) and poll jobs via 202 Accepted (ADP-026).
1. Signed webhook delivery (ADP-025)
Sign <webhook-id>.<webhook-timestamp>.<raw-body> with HMAC-SHA256, verify in constant time, and reject timestamps older than 5 minutes. Receivers should deduplicate using Webhook-Id.
POST https://consumer.example.com/webhooks/orders HTTP/1.1 Webhook-Id: msg_01J9Z9P3K2M4 Webhook-Timestamp: 1763290000 Webhook-Signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=
2. Async job pattern with 202 Accepted (ADP-026)
Never hold HTTP connections open for slow exports or batch imports. Return 202 Accepted with a Location header pointing to a job status resource.
HTTP/1.1 202 Accepted Location: /v1/jobs/job_01J9Z9T4 Retry-After: 5