● Webhook management · /v1

Webhook management

Register endpoints, rotate secrets, inspect deliveries and replay them. After an outage on your side, this is how you catch up without contacting us.

List webhook endpoints

GET /v1/webhooks/endpoints

Response 200

uid string
url string Must be https. We never deliver over http
events string[] Event types to subscribe to; an empty array subscribes to everything
status active | paused | disabled paused means delivery stopped automatically after repeated failures; fix your endpoint, then replay
description string
secret_preview string The secret is returned in full only at creation and rotation; afterwards only the last characters
created_at string<date-time>
Request
curl -X GET https://api.baton.example/v1/webhooks/endpoints \
  -H "Authorization: Bearer sk_live_xxx"
Response · 200
[
  {
    "uid": "WE20261116000001",
    "url": "https://hooks.example.com/baton",
    "events": [
      "payment.status_changed",
      "refund.status_changed"
    ],
    "status": "active",
    "secret_preview": "...7f3a",
    "created_at": "2026-10-02T03:11:00Z"
  }
]

Register a webhook endpoint

POST /v1/webhooks/endpoints

Must be a publicly reachable https URL; private and reserved addresses are rejected. The signing secret is returned in full only in this response — afterwards you only get the last characters, so a secret you failed to store can only be rotated.

Headers

Idempotency-Keyrequired string A unique string you generate (UUID/ULID recommended). Replaying the same key within 24 hours returns the original result and never creates a second payment.

Body

urlrequired string
events string[] Leave empty to subscribe to everything. Listing them explicitly is recommended, so a newly added event type does not suddenly hit your existing handler
description string

Errors

400Invalid parameters
Request
curl -X POST https://api.baton.example/v1/webhooks/endpoints \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..." \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://hooks.example.com/baton",
  "events": [
    "payment.status_changed",
    "refund.status_changed"
  ],
  "description": "prod order service"
}'
Response · 201
{
  "uid": "WE20261116000001",
  "url": "https://hooks.example.com/baton",
  "events": [
    "payment.status_changed"
  ],
  "status": "active",
  "secret": "whsec_live_9f3a2c7e...",
  "created_at": "2026-11-16T09:45:00Z"
}

Rotate the signing secret

POST /v1/webhooks/endpoints/{uid}/rotate-secret

Old and new secrets are both valid for 24 hours during rotation, and the webhook header carries two v1= values — verifying against either is enough. Once your fleet has moved over, the old secret expires by itself. No downtime needed.

Path parameters

uidrequired string

Headers

Idempotency-Keyrequired string A unique string you generate (UUID/ULID recommended). Replaying the same key within 24 hours returns the original result and never creates a second payment.

Response 200

secret string
old_secret_expires_at string<date-time>
Request
curl -X POST https://api.baton.example/v1/webhooks/endpoints/{uid}/rotate-secret \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..."
Response · 200
{
  "secret": "whsec_live_2b8e41d0...",
  "old_secret_expires_at": "2026-11-17T09:45:00Z"
}

Delivery log

GET /v1/webhooks/deliveries

Start with response_excerpt — that is the first 512 bytes of your own response. Nine times out of ten, "we never got the webhook" turns out to be a 500 or a response slower than 5 seconds.

Query parameters

event_id string
endpoint_uid string
status pending | delivered | failed | abandoned
created_from string<date-time>
created_to string<date-time>
cursor string The page.next_cursor returned by the previous page
limit integer

Response 200

data object[]
└uid string
└event_id string Event ID — use this one for idempotent deduplication
└event_type string
└endpoint_uid string
└status pending | delivered | failed | abandoned
└http_status integer
└response_excerpt string The first 512 bytes of your own response, stored redacted. Start debugging here
└attempt_no integer
└next_retry_at string<date-time>
└created_at string<date-time>
page object
└next_cursor string
└has_more boolean
Request
curl -X GET https://api.baton.example/v1/webhooks/deliveries \
  -H "Authorization: Bearer sk_live_xxx"

Replay a webhook

POST /v1/webhooks/deliveries/{uid}/resend

After an outage on your side, catch up with this instead of contacting us. A replay keeps the same event id, so your idempotent deduplication has to be working first — otherwise every replay is another duplicate.

To replay in bulk: list deliveries filtered by date range and status=failed, then replay each one.

Path parameters

uidrequired string

Headers

Idempotency-Keyrequired string A unique string you generate (UUID/ULID recommended). Replaying the same key within 24 hours returns the original result and never creates a second payment.

Response 202

uid string
event_id string Event ID — use this one for idempotent deduplication
event_type string
endpoint_uid string
status pending | delivered | failed | abandoned
http_status integer
response_excerpt string The first 512 bytes of your own response, stored redacted. Start debugging here
attempt_no integer
next_retry_at string<date-time>
created_at string<date-time>

Errors

404The object does not exist, or belongs to another environment or merchant
Request
curl -X POST https://api.baton.example/v1/webhooks/deliveries/{uid}/resend \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..."

Delete a webhook endpoint

POST /v1/webhooks/endpoints/{uid}/delete

Deliveries already in flight finish their current attempt; nothing disappears mid-retry.

Path parameters

uidrequired string

Response 200

uid string
deleted boolean

Errors

404The object does not exist, or belongs to another environment or merchant
Request
curl -X POST https://api.baton.example/v1/webhooks/endpoints/{uid}/delete \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..."