API Reference

Webhooks API

Manage your webhook endpoints — create, read, update, delete, rotate signing secrets, and trigger test events.

Base URL

https://api.xrnotify.io/v1

POST/v1/webhooks

Create a new webhook endpoint. Returns the webhook object including the signing secret — this is the only time the secret is shown.

Request body

Field	Type	Required	Description
`url`	`string`	Required	HTTPS endpoint to deliver events to
`event_types`	`string[]`	Required	Event types to subscribe to (e.g. ["payment.xrp"])
`description`	`string`	Optional	Human-readable label for your own reference
`account_filters`	`string[]`	Optional	Restrict to specific XRPL account addresses. Empty = all accounts
`is_active`	`boolean`	Optional	Whether to start delivering immediately. Default: true

Request

curl -X POST https://api.xrnotify.io/v1/webhooks \
  -H "X-XRNotify-Key: xrn_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/xrpl",
    "event_types": ["payment.xrp"],
    "description": "Main handler"
  }'

Response 201 Created

{
  "id": "wh_abc123",
  "url": "https://yourapp.com/webhooks/xrpl",
  "description": "Main handler",
  "event_types": ["payment.xrp"],
  "account_filters": [],
  "is_active": true,
  "created_at": "2024-01-15T10:00:00Z",
  "secret": "whsec_xxxxxxxxxxxxxxxx"
}

GET/v1/webhooks

List all webhooks for your account. Results are paginated using cursor-based pagination.

Query parameters

Parameter	Default	Description
`limit`	`20`	Results per page. Max 100.
`cursor`	`—`	Pagination cursor from a previous response's `next_cursor`

Request

curl "https://api.xrnotify.io/v1/webhooks?limit=10" \
  -H "X-XRNotify-Key: xrn_live_..."

Response 200 OK

{
  "data": [
    {
      "id": "wh_abc123",
      "url": "https://yourapp.com/...",
      "event_types": ["payment.xrp"],
      "is_active": true,
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET/v1/webhooks/:id

Retrieve a single webhook by ID. The response does not include the signing secret.

Request

curl https://api.xrnotify.io/v1/webhooks/wh_abc123 \
  -H "X-XRNotify-Key: xrn_live_..."

Response 200 OK

{
  "id": "wh_abc123",
  "url": "https://yourapp.com/webhooks/xrpl",
  "description": "Main handler",
  "event_types": ["payment.xrp"],
  "account_filters": [],
  "is_active": true,
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z"
}

PATCH/v1/webhooks/:id

Update a webhook. Send only the fields you want to change — all others remain unchanged.

Updatable fields: url, event_types, account_filters, description, is_active

Request

curl -X PATCH https://api.xrnotify.io/v1/webhooks/wh_abc123 \
  -H "X-XRNotify-Key: xrn_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event_types": ["payment.xrp", "nft.minted"],
    "is_active": true
  }'

Response 200 OK

{
  "id": "wh_abc123",
  "url": "https://yourapp.com/webhooks/xrpl",
  "event_types": ["payment.xrp", "nft.minted"],
  "is_active": true,
  "updated_at": "2024-01-15T11:00:00Z"
}

DELETE/v1/webhooks/:id

Permanently delete a webhook. All pending deliveries are cancelled. This action cannot be undone.

Request

curl -X DELETE https://api.xrnotify.io/v1/webhooks/wh_abc123 \
  -H "X-XRNotify-Key: xrn_live_..."

Response

204 No Content

POST/v1/webhooks/:id/rotate-secret

Generate a new signing secret for the webhook. The new secret is returned once in the response and the old secret is immediately invalidated.

Warning: The old secret is invalidated immediately upon rotation. Update your WEBHOOK_SECRET environment variable and redeploy your application before rotating in production to avoid verification failures.

Request

curl -X POST \
  https://api.xrnotify.io/v1/webhooks/wh_abc123/rotate-secret \
  -H "X-XRNotify-Key: xrn_live_..."

Response 200 OK

{
  "secret": "whsec_new_secret_shown_once"
}

POST/v1/webhooks/:id/test

Send a synthetic test event to the webhook endpoint. Useful for verifying your signature verification code and endpoint reachability without waiting for a real XRPL event.

Field	Type	Required	Description
`event_type`	`string`	Optional	Event type to simulate. Defaults to the first event type on the webhook.

Request

curl -X POST \
  https://api.xrnotify.io/v1/webhooks/wh_abc123/test \
  -H "X-XRNotify-Key: xrn_live_..." \
  -H "Content-Type: application/json" \
  -d '{"event_type": "payment.xrp"}'

Response 200 OK

{
  "delivery_id": "dlv_test_xyz789",
  "status": "delivered",
  "response_status": 200
}

Deliveries API

Monitor and retry event deliveries

Verify Signatures

Secure your webhook endpoint

Replay API

Re-deliver past events

Webhooks API

Request body

Query parameters

Related