Webhook Management
Discover and manage webhook subscriptions
bearerAuth Your secret key, sent as Authorization: Bearer cf_live_<key_id>_<secret>.
In: header
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v3/webhooks/event-types"{ "object": "list", "has_more": false, "data": [ { "object": "webhook_event_type", "event_type": "alerts.created", "description": "A new alert arrived. `data` is the alert.", "status": "available" }, { "object": "webhook_event_type", "event_type": "alerts.enrollment.status_changed", "description": "Platform key only. One provider's status on an alert enrollment changed.", "status": "coming_soon" }, { "object": "webhook_event_type", "event_type": "alerts.transaction.linked", "description": "An alert was matched to a transaction.", "status": "available" }, { "object": "webhook_event_type", "event_type": "alerts.updated", "description": "An alert changed, usually because an outcome was reported.", "status": "available" }, { "object": "webhook_event_type", "event_type": "dispute.created", "description": "A dispute arrived, from a connected processor or created through the API.", "status": "available" }, { "object": "webhook_event_type", "event_type": "evidence.error", "description": "Platform key only. Evidence generation failed.", "status": "coming_soon" }, { "object": "webhook_event_type", "event_type": "evidence.ready", "description": "Platform key only. Evidence generation finished.", "status": "coming_soon" }, { "object": "webhook_event_type", "event_type": "*", "description": "Every event type, current and future.", "status": "available" } ]}bearerAuth Your secret key, sent as Authorization: Bearer cf_live_<key_id>_<secret>.
In: header
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v3/webhooks/registrations"{ "object": "list", "has_more": false, "data": [ { "id": "whr_0199a3c4-5d6e-7f80-9a1b-2c3d4e5f6a7b", "object": "webhook_registration", "url_target": "https://partner.example/hooks/chargeflow", "event_types": [ "dispute.created", "evidence.ready" ], "is_active": true, "created_at": "2026-10-20T09:30:00.000Z", "updated_at": "2026-10-20T09:30:00.000Z", "livemode": true } ]}bearerAuth Your secret key, sent as Authorization: Bearer cf_live_<key_id>_<secret>.
In: header
application/json
The https URL that receives deliveries. Cannot be changed later. It must carry no username or password and not point at a private, loopback, link-local or cloud-metadata address (400 WEBHOOK_URL_TARGET_INVALID). One registration per URL per account: a second, including a retried create, is 409 WEBHOOK_ALREADY_EXISTS.
uriAt least one (400 WEBHOOK_EVENT_TYPES_REQUIRED). Duplicates are dropped.
["*"] alone subscribes to every type, current and future. * mixed with specific types is 409 WEBHOOK_WILDCARD_ALREADY_EXISTS. A type your key cannot see (unknown, or platform-only on a merchant key) is 400 WEBHOOK_EVENT_TYPES_INVALID.
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v3/webhooks/registrations" \ -H "Content-Type: application/json" \ -d '{ "url_target": "https://partner.example/hooks/chargeflow", "event_types": [ "dispute.created", "evidence.ready" ] }'{ "id": "whr_0199a3c4-5d6e-7f80-9a1b-2c3d4e5f6a7b", "object": "webhook_registration", "url_target": "https://partner.example/hooks/chargeflow", "event_types": [ "dispute.created", "evidence.ready" ], "is_active": true, "created_at": "2026-10-20T09:30:00.000Z", "updated_at": "2026-10-20T09:30:00.000Z", "livemode": true, "signing_secret": "whsec_3f8a1c9b2d7e4a6f0b5c8d1e3a7f9b2c4d6e8a0b1c3"}bearerAuth Your secret key, sent as Authorization: Bearer cf_live_<key_id>_<secret>.
In: header
The registration id (whr_ prefix).
application/json
Send at least one field.
Replaces the whole list. Same rules as on create, including *.
false pauses delivery from the next event and keeps the id and signing secret. true resumes it.
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/v3/webhooks/registrations/whr_0199a3c4-5d6e-7f80-9a1b-2c3d4e5f6a7b" \ -H "Content-Type: application/json" \ -d '{ "event_types": [ "dispute.created" ], "is_active": true }'{ "id": "whr_0199a3c4-5d6e-7f80-9a1b-2c3d4e5f6a7b", "object": "webhook_registration", "url_target": "https://partner.example/hooks/chargeflow", "event_types": [ "dispute.created" ], "is_active": true, "created_at": "2026-10-20T09:30:00.000Z", "updated_at": "2026-10-21T14:05:00.000Z", "livemode": true}bearerAuth Your secret key, sent as Authorization: Bearer cf_live_<key_id>_<secret>.
In: header
The registration id (whr_ prefix).
application/json
application/json
application/json
application/json
application/json
curl -X DELETE "https://example.com/v3/webhooks/registrations/whr_0199a3c4-5d6e-7f80-9a1b-2c3d4e5f6a7b"bearerAuth Your secret key, sent as Authorization: Bearer cf_live_<key_id>_<secret>.
In: header
The registration id (whr_ prefix).
application/json
A specific type your key can see. *, an unknown type, or a platform-only type on a merchant key returns 400 WEBHOOK_EVENT_TYPES_INVALID. It does not need to be a type the registration subscribes to.
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v3/webhooks/registrations/whr_0199a3c4-5d6e-7f80-9a1b-2c3d4e5f6a7b/test" \ -H "Content-Type: application/json" \ -d '{ "event_type": "dispute.created" }'{ "id": "whd_0199a3c5-7b1e-7c2a-9f4d-3e8b6a1c0d2f", "object": "webhook_test_delivery", "livemode": true}