Webhooks
Error Handling and Best Practices
| HTTP status | Meaning |
|---|
400 | The request was invalid. The body describes the problem and includes an error code. |
401 | Missing or invalid access token. |
404 | Webhook registration not found. |
500 | An error occurred on Xe's platform. |
| Code | Description |
|---|
7001 | Webhook registration not found |
7002 | Failed to save webhook registration |
7003 | Failed to create webhook registration (includes exceeding the per-account limit) |
7004 | Failed to delete webhook registration |
7006 | Webhook registration has duplicate header keys |
7007 | A webhook is already registered for this URL |
7008 | Webhook registration has an invalid event type |
7011 | Webhook registration URL is not valid |
7012 | Webhook registration URL resolves to an internal address |
7013 | Webhook registration URL redirects to another location |
7014 | Webhook registration URL could not be reached |
Keep the traceErrorId from any error response when contacting support — it lets Xe trace the specific failed call.
- Respond fast with a 2xx. Xe waits up to 30 seconds. Acknowledge immediately (e.g.
200/204) and do heavy processing asynchronously.
- Return the right status code.
408, 429 and 5xx are retried; any other 4xx is treated as permanent and the event is not resent.
- Design for duplicates and out-of-order delivery. Use
EventId to ignore duplicates, make handling idempotent, and do not rely on arrival order.
- Don't trust the payload alone for money-moving decisions. Use the webhook as a “go look” signal and confirm latest state with Pay API calls using the references in the payload.
- Ignore unknown fields. New fields may be added to
Data; do not fail on fields you don't recognize.
- Monitor
status and disabledReason. Periodically call GET /v2/webhook-registrations and alert if any registration is not Active.
| Method | Path | Purpose |
|---|
POST | /v2/webhook-registrations | Register a new webhook |
GET | /v2/webhook-registrations | List all webhook registrations |
GET | /v2/webhook-registrations/{id} | Retrieve one webhook registration |
DELETE | /v2/webhook-registrations/{id} | Delete a webhook registration |