Create a webhook endpoint with the event types your integration needs. Store its signing secret in a secret manager and never expose it to the browser.

​
Handler checklist

  • Capture the raw body before JSON parsing.
  • Validate the signature, timestamp, and endpoint secret.
  • Reject malformed or unauthorized requests.
  • Insert the event ID into a unique store before applying effects.
  • Queue long-running work and acknowledge quickly.
  • Record processing outcome and last error.
  • Retry transient failures without replaying a financial transition.
  • Alert on repeated failures and stale event backlog.

​
Reconciliation

If an event is delayed or your handler was unavailable, list or retrieve the event and reconcile the affected resource. Do not create a replacement payment just because delivery was delayed.