Webhooks API

Webhook Endpoints

POST /webhook-endpoints

Field	Type	Required	Description
`url`	string	yes	Your HTTPS endpoint URL
`events`	array	no	Event types to subscribe to. Omit for all events.
`description`	string	no	Internal label

curl https://api.xtopay.co/v1/webhook-endpoints \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/xtopay",
    "events": ["payment.succeeded", "subscription.cancelled"]
  }'

Response 201

{
  "id": "we_a1b2c3",
  "url": "https://yourapp.com/webhooks/xtopay",
  "events": ["payment.succeeded", "subscription.cancelled"],
  "status": "active",
  "created_at": "2026-05-24T10:00:00Z"
}

GET /webhook-endpoints/:id

Retrieve a webhook endpoint.

PATCH /webhook-endpoints/:id

Update URL or event subscriptions.

DELETE /webhook-endpoints/:id

Delete a webhook endpoint. Stops all deliveries immediately.

GET /webhook-endpoints

List all registered endpoints.

Events

GET /events/:id

Retrieve a specific event by ID.

{
  "id": "evt_a1b2c3",
  "type": "payment.succeeded",
  "created_at": "2026-05-24T10:02:14Z",
  "data": { ... }
}

GET /events

List events in reverse chronological order.

Parameter	Description
`type`	Filter by event type
`created_after`	ISO 8601 timestamp
`created_before`	ISO 8601 timestamp
`limit`	1–100, default 20
`after`	Cursor

Delivery Attempts

GET /events/:id/delivery-attempts

List delivery attempts for an event.

[
  {
    "id": "da_a1b2c3",
    "event_id": "evt_abc",
    "endpoint_id": "we_xyz",
    "status": "failed",
    "response_status": 500,
    "response_body": "Internal Server Error",
    "attempted_at": "2026-05-24T10:02:15Z",
    "next_retry_at": "2026-05-24T10:07:15Z"
  }
]

POST /events/:id/replay

Manually replay an event to all active endpoints.

curl -X POST https://api.xtopay.co/v1/events/evt_a1b2c3/replay \
  -u "$CLIENT_ID:$CLIENT_SECRET"

On this page