Webhook Delivery and Security
Webhook registration, event filtering, signature verification, and retry strategy.
Webhooks carry payment outcomes to your server in a reliable, repeatable way. Redirect or confirm responses guide the user experience; the decision to close an order should come from a webhook or a server-side payment query.
Configuration
Typical fields for each endpoint:
- HTTPS URL
- Event types to listen for
- Signature verification secret
If you do not send a secret, the platform may generate a key; in production you should manage the secret yourself and rotate it periodically. Enable only the events you need; this reduces noise and the risk of incorrect processing.
Payment event family (example)
Common types on the merchant side:
| Event | When to consider it |
|---|---|
payment.succeeded | Capture completed |
payment.authorized | Auth-only success (auto_capture: false) |
payment.requires_action | 3DS or an extra user step |
payment.requires_payment_method | Missing method or last attempt failed |
payment.canceled / payment.refunded | Cancel or refund |
payment.processing | Intermediate state (if present) |
On the charge side, events such as charge.declined and charge.captured can be used for operational detail. Match them in your handler using the payment ID.
Delivery lifecycle
A delivery record roughly moves through these states:
| Status | Meaning |
|---|---|
PENDING | Queued, no attempt yet |
PROCESSING | Sending to the endpoint |
SUCCEEDED | 2xx received |
FAILED | Retries exhausted or permanent error |
Each failed attempt gets its own attempt record; the retry window is visible via next_retry_at.
Retry and resilience
- Retries run on network outages and selected HTTP errors.
- Wait times increase in stages.
- After the upper limit, delivery becomes
FAILED; plan alerts and manual review.
The merchant handler must be idempotent: even if the same event or payment ID arrives again, there must be no double capture or double order closure.
Security checklist
- Endpoint is HTTPS only.
- State is not updated until the incoming signature is verified.
- PAN, CVV, provider secrets, or raw challenge HTML are not logged.
- A 2xx response is returned only after business logic completes successfully.
Recommended handler flow
- Verify the signature.
- Check whether the event ID or payment ID was already processed.
- Update domain state (order, subscription, invoice).
- Return 2xx.
Account scope
Webhook settings are account-scoped. In multi-account setups, confirm on your operations checklist that each endpoint is tied to the correct account.