● 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.
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
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"
} 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
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"
} 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
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
| 404 | The 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=..." POST /v1/webhooks/endpoints/{uid}/delete
Deliveries already in flight finish their current attempt; nothing disappears mid-retry.
Path parameters
Response 200
uid | string | |
deleted | boolean | |
Errors
| 404 | The 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=..."