Endpoints

Register webhook

POST/api/v1/webhooks

POST/api/v1/webhookssecret key

Body parameters

urlstring
HTTPS endpoint that will receive the deliveries. If you omit it, we auto-generate a URL on our domain (managed inbox) and the response includes `managed: true`.
eventsstring[]required
List of event names from the catalogue (see Webhooks & signing). `["*"]` subscribes to all of them.
descriptionstring
Free-form label (≤240 chars) — visible in the dashboard to distinguish multiple subscriptions.

Request

curl https://sandbox.key2pay.ai/api/v1/webhooks \
  -H "Authorization: Bearer sk_test_51N8mP...exampleK3Y" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://acme.com/webhooks/key2pay", "events": ["payment.completed"] }'

Response

{
  "id": "wh_2zP97…",
  "url": "https://acme.com/webhooks/key2pay",
  "events": ["payment.completed"],
  "secret": "whsec_2zP97…",
  "managed": false,
  "active": true,
  "createdAt": "2026-05-12T15:24:27.426Z"
}