curl -X POST https://catchbackcards.com/api/partner/v2/webhooks \
-H "Authorization: Bearer $CATCHBACK_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://partner.example.com/catchback/webhooks" }'
{
"webhook": {
"id": "c2f0e8b4-1a7d-4c39-9e55-0b6d3a8f2e17",
"url": "https://partner.example.com/catchback/webhooks",
"enabled": true,
"created_at": "2026-11-17T10:00:00.000Z",
"updated_at": "2026-11-17T10:00:00.000Z"
},
"secret": "whsec_3f9a..."
}
{
"webhook": {
"id": "c2f0e8b4-1a7d-4c39-9e55-0b6d3a8f2e17",
"url": "https://partner.example.com/catchback/webhooks-v2",
"enabled": true,
"created_at": "2026-11-17T10:00:00.000Z",
"updated_at": "2026-11-17T11:30:00.000Z"
},
"secret": null
}
Webhook endpoints
Register a webhook
Register your key’s webhook URL, or change it. The signing secret is shown once.
POST
/
api
/
partner
/
v2
/
webhooks
curl -X POST https://catchbackcards.com/api/partner/v2/webhooks \
-H "Authorization: Bearer $CATCHBACK_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://partner.example.com/catchback/webhooks" }'
{
"webhook": {
"id": "c2f0e8b4-1a7d-4c39-9e55-0b6d3a8f2e17",
"url": "https://partner.example.com/catchback/webhooks",
"enabled": true,
"created_at": "2026-11-17T10:00:00.000Z",
"updated_at": "2026-11-17T10:00:00.000Z"
},
"secret": "whsec_3f9a..."
}
{
"webhook": {
"id": "c2f0e8b4-1a7d-4c39-9e55-0b6d3a8f2e17",
"url": "https://partner.example.com/catchback/webhooks-v2",
"enabled": true,
"created_at": "2026-11-17T10:00:00.000Z",
"updated_at": "2026-11-17T11:30:00.000Z"
},
"secret": null
}
Scope:
nft:orders
Registers this key’s webhook (201, with the signing secret, shown once), or changes its URL (200, "secret": null: the secret stays the same). Events, signatures and retries: Webhooks.
- One webhook per key. To get a new secret, delete the webhook and register again.
- A key that has been rotated can’t register or re-enable a webhook (
409 KEY_ROTATED). A rotation moves the webhook to the new key by itself.
A public
https:// URL on port 443, with a hostname (not an IP address) and no login in it, up to 2048 characters. The sandbox has the same rule: to receive on your own machine, use a tunnel such as ngrok.Response
id, url, enabled, created_at and updated_at. Use id with Test a webhook and Delete a webhook.The signing secret,
whsec_..., on the first registration only. Store it: it is never returned again. null when you changed the URL of an existing webhook.Errors
| Status | Code | When |
|---|---|---|
400 | BAD_JSON | The body isn’t JSON |
400 | INVALID_WEBHOOK_URL | The URL isn’t a public https:// URL; the message says why |
409 | KEY_ROTATED | This key has been rotated; register the webhook with the new key |
409 | WEBHOOK_ACCOUNT_CHANGED | This key’s webhook was registered under an earlier setup of your program; DELETE it and register again |
503 | WEBHOOKS_UNAVAILABLE | Webhooks aren’t available on this server yet |
curl -X POST https://catchbackcards.com/api/partner/v2/webhooks \
-H "Authorization: Bearer $CATCHBACK_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://partner.example.com/catchback/webhooks" }'
{
"webhook": {
"id": "c2f0e8b4-1a7d-4c39-9e55-0b6d3a8f2e17",
"url": "https://partner.example.com/catchback/webhooks",
"enabled": true,
"created_at": "2026-11-17T10:00:00.000Z",
"updated_at": "2026-11-17T10:00:00.000Z"
},
"secret": "whsec_3f9a..."
}
{
"webhook": {
"id": "c2f0e8b4-1a7d-4c39-9e55-0b6d3a8f2e17",
"url": "https://partner.example.com/catchback/webhooks-v2",
"enabled": true,
"created_at": "2026-11-17T10:00:00.000Z",
"updated_at": "2026-11-17T11:30:00.000Z"
},
"secret": null
}

