Webhook Operations

Webhooks are operational plumbing, not just a convenience feature. Treat them as a durable event stream that can arrive late, out of order, or more than once.

Delivery Model

deliveries are asynchronous
retries can happen
the same event_id can show up more than once
downstream business logic must be idempotent

Recommended Handler Shape

authenticate the delivery
record event_id
enqueue the event for async processing
return a fast success response
replay safely if the same event arrives again

What To Persist

At minimum, keep:

event_id
event_type
object_id
profile_id
receipt timestamp
processing result

When To Use the Events API

Use the Events API or dashboard delivery history when:

a merchant says they never saw a webhook
you need the exact request and response bodies from a failed delivery
you want to retry a delivery after fixing your receiver

Fulfillment Rule

Never fulfill from the browser redirect alone. Fulfill from a verified webhook or from a trusted server-side retrieval after the final payment state is available.