Register and manage webhooks

Call POST /v2/webhook-registrations with the HTTPS URL you want events sent to.

Request

POST /v2/webhook-registrations HTTP/1.1
Host: pay-api.xe.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
  "uri": "https://example.com/hooks/xe",
  "headers": [
    { "key": "Api-Key", "value": "your-secret" }
  ],
  "subscribeToAll": false,
  "eventTypes": ["Payment.Completed", "Batch.Created"]
}

Response

// 201 Created
{
  "id": "3f1c2a8e-6b0d-4e57-9a1c-0d2f7c5b9e41",
  "uri": "https://example.com/hooks/xe",
  "headers": [
    { "key": "Api-Key", "value": "your-secret" }
  ],
  "subscribeToAll": false,
  "eventTypes": ["Payment.Completed", "Batch.Created"],
  "status": "Active",
  "disabledReason": null
}

Request Parameter Details

Field	Type	Required	Description
`uri`	string	Yes	The HTTPS URL that will receive events. See Destination URL requirements below.
`headers`	array of header	Yes	Custom HTTP headers to include with each event delivered to your URL (for example, an authorization header your endpoint expects). Each header is `{ "key": "...", "value": "..." }`. Keys must be unique.
`subscribeToAll`	boolean	No	When `true`, you receive all event types and `eventTypes` is ignored.
`eventTypes`	array of string	No	The event types to receive. Used when `subscribeToAll` is not `true`. See Event types above.

To receive every event type without maintaining a list, set subscribeToAll: true and omit eventTypes.

Rules and limits

You can have a limited number of webhook registrations per account (currently 3). Delete an existing registration to free a slot.
You cannot register the same URL twice. URLs are compared case-insensitively and ignoring a trailing /.
Xe checks the destination when you register. The registration is rejected if the host cannot be resolved, resolves to a non-public address, or does not respond acceptably (see error codes below).

Destination URL requirements

Your uri must:

be an absolute URL of 2048 characters or fewer;
use https;
use a host name, not an IP address;
use the default HTTPS port (443);
not contain credentials (user:password@);
not contain a fragment (#...);
resolve to a publicly routable address (hosts that resolve to loopback, private, link-local, shared or reserved ranges are rejected);
not respond with a redirect (register the final URL instead).

Webhook lifecycle and status

Every registration reports a status:

Status	Meaning
`Active`	Registration is recognized by Xe and events are delivered.
`Disabled`	Registration still exists but has been disabled by Xe. See `disabledReason`.

When status is Disabled, the disabledReason field (max 500 characters) explains why Xe disabled the registration. It is only set when status is Disabled.

There is no update/pause/re-enable API: to change a registration (URL, headers, subscriptions), delete it and register a new one.

Managing registrations

List all webhooks — GET /v2/webhook-registrations returns a JSON array of your webhook registration objects (empty array if none).

// 200 OK
[
  {
    "id": "3f1c2a8e-6b0d-4e57-9a1c-0d2f7c5b9e41",
    "uri": "https://example.com/hooks/xe",
    "headers": [],
    "subscribeToAll": true,
    "eventTypes": [],
    "status": "Active",
    "disabledReason": null
  }
]

Get one webhook — GET /v2/webhook-registrations/{id} returns a single registration by the id returned when it was created. Returns 404 if no registration with that id exists on your account.

Delete a webhook — DELETE /v2/webhook-registrations/{id} deletes the registration; events are no longer sent to its URL. Returns 204 No Content on success and 404 if it does not exist on your account.

Webhook registration object

Field	Type	Description
`id`	string	Unique identifier of the registration.
`uri`	string	Destination URL.
`headers`	array of header	Custom headers sent with each delivery.
`subscribeToAll`	boolean	`true` if subscribed to all event types.
`eventTypes`	array of string	Subscribed event types; empty when `subscribeToAll` is `true`.
`status`	string	`Pending`, `Active` or `Disabled`.
`disabledReason`	string or null	Why Xe disabled the registration (max 500 characters). Only set when `status` is `Disabled`.

Register and manage webhooks

On this page