Guides/Payment flows
Webhooks
Receive events securely with signature validation, deduplication and controlled retries.
Webhooks notify your backend when a payment, payout or other resource changes state.
Endpoint requirements
Use a public HTTPS endpoint. Read the raw request body before JSON parsing when validating the signature, and return HTTP 200 quickly after the event is durably accepted.
Safe processing flow
Read the raw body
Keep the exact bytes used to calculate the signature.Validate authenticity
Compare signatures using a timing-safe method and reject invalid requests.Deduplicate
Insert the event id into a table with a unique constraint. If it already exists, return 200 without processing again.Apply the state change
Update your resource atomically and tolerate events arriving out of order.Respond quickly
Queue slow work and acknowledge the delivery before your endpoint times out.
Retries
Non-2xx responses and timeouts may cause redelivery. Duplicate delivery is normal, so correctness must not depend on receiving an event exactly once.
Security
Never trust an event only because it reached a secret-looking URL. Always validate its cryptographic signature.