How the signature is built
x-stableyard-signature has the form t=<timestamp>,v1=<hmac_sha256>. The digest is HMAC-SHA256, hex-encoded, over:
GET /v2/partners/config describes the same scheme under capabilities.webhooks.signatures, so you can check your implementation against the environment you call:
Verify a delivery
Verify the raw request bytes before JSON parsing, require the signed timestamp to matchx-stableyard-timestamp, reject timestamps outside a short tolerance, and compare digests in constant time.
x-stableyard-timestamp and signature, so the timestamp check passes for a legitimate retry.
After verifying
Parse the JSON and apply the event in the same database transaction that recordsx-stableyard-event-id under a unique constraint. If that insert conflicts, return 2xx without applying the business effect again.
Do not mark an event processed before its business update commits: a crash in between permanently loses the event. Timestamp validation limits replay of a captured request; durable event-ID deduplication handles legitimate redelivery.
Rotating the signing secret
Rotate a secret in the Partner Dashboard: open Developers → Webhooks and choose Rotate signing secret on the endpoint. The new secret is shown once, and the previous one stops working at once: there is no overlap window. Deliveries and retries sent after the rotation are signed with the new secret, so deploy it to your handler immediately after you rotate. An archived endpoint cannot rotate its secret.When verification fails
Respond to a failed verification with a non-
2xx status. A 4xx other than 408, 425 or 429 is not retried. See Delivery and retries.
Related
Webhooks overview
Endpoints, headers and a minimal handler.
Delivery and retries
What happens when your handler fails.
Event catalog
Every partner event and its payload.
Reconciliation
Survive duplicates and reordering.