Verify before parsing
Read the exact raw request body. The signature uses HMAC-SHA256 overid.timestamp.rawBody, with the base64-decoded key after the whsec_ prefix. Headers are webhook-id, webhook-timestamp and webhook-signature; the signature value starts with v1,.
Use a constant-time comparison and reject timestamps outside your accepted replay window. Parsing and reserializing JSON before verification changes the signed bytes. The existing Console integration examples use a five-minute timestamp window.
Process idempotently
1
Verify the signature
Reject invalid signatures and timestamps before processing the payload.
2
Deduplicate the delivery
Store the webhook ID under a unique constraint. A repeated ID must not repeat business side effects.
3
Commit the event and work
Atomically record the accepted event and your durable work or state change. Handle events that arrive late or out of order.
4
Acknowledge after commit
Return a successful response only after durable acceptance. A replay of an already accepted event can return success without repeating the work.
Testing and rotation
Use the delivery history to inspect failures and replay a delivery after fixing the receiver. A replay still requires deduplication. Secret rotation is a separate action; coordinate the receiver with the connection’s current signing configuration.Simulator events are useful for application testing but do not verify the live provider callback chain. Confirm that live webhook dispatch is enabled before relying on it for production workflows.