Webhooks

Receive real-time notifications when payment events occur in your application.

Overview

kadosei sends webhook notifications to your server when the status of a payment session changes. This is the recommended way to handle payment outcomes rather than polling the session status endpoint.

Each webhook configuration is scoped to an application. When an event occurs, kadosei sends an HTTP POST request to the URL you have registered for that application.

Webhook management uses your JWT for authentication, not an API key.

Register a webhook

POST /api/v1/applications/{applicationId}/webhooks

{
  "url": "https://merchant.example.com/webhooks/kadosei",
  "subscribedEvents": [
    "session.completed",
    "session.expired"
  ]
}

url is required and must be an HTTPS endpoint. subscribedEvents is optional, if omitted, a default set of events will be subscribed. See Event types for available values.

{
  "id": "8a1c2f9e-3d4b-4f5a-9b6c-7d8e9f0a1b2c",
  "url": "https://merchant.example.com/webhooks/kadosei",
  "isActive": true,
  "keyFingerprint": "whsec_...a3f2",
  "signingSecret": "whsec_full_secret_value",
  "subscribedEvents": [
    "session.completed",
    "session.expired"
  ],
  "lastTestAt": null,
  "lastTestStatus": null,
  "createdAt": "2026-01-15T08:00:00.000Z",
  "updatedAt": null
}

The signingSecret is returned only once. Store it securely immediately as it cannot be retrieved again. If you lose it, you will need to delete this webhook and create a new one.

Errors

Status	Description
`400`	Validation failed. Check the URL is a valid HTTPS address and all event names are recognised
`401`	Missing or invalid JWT
`403`	You do not have permission to manage webhooks for this application
`404`	Application not found

Verifying webhook signatures

Every webhook delivery includes a signature in the request headers. You should verify this signature before processing any event to confirm the request came from kadosei.

kadosei signs webhook payloads using HMAC-SHA256 with your signingSecret. Use the keyFingerprint field to identify which signing key was used, which is useful if you rotate keys.

Event types

Event	When it fires
`session.completed`	A payment session was completed successfully
`session.expired`	A payment session expired before the customer completed checkout

List webhooks

Retrieve all webhook configurations for an application.

GET /api/v1/applications/{applicationId}/webhooks?page=1&limit=10

{
  "items": [
    {
      "id": "8a1c2f9e-3d4b-4f5a-9b6c-7d8e9f0a1b2c",
      "url": "https://merchant.example.com/webhooks/kadosei",
      "isActive": true,
      "keyFingerprint": "whsec_...a3f2",
      "subscribedEvents": [
        "session.completed",
        "session.expired"
      ],
      "lastTestAt": "2026-04-20T12:34:56.000Z",
      "lastTestStatus": "SUCCEEDED",
      "createdAt": "2026-01-15T08:00:00.000Z",
      "updatedAt": "2026-04-01T09:30:00.000Z"
    }
  ],
  "page": 1,
  "limit": 10,
  "totalItems": 1,
  "totalPages": 1,
  "hasPreviousPage": false,
  "hasNextPage": false
}

Note that signingSecret is never returned on list or subsequent GET responses. Only keyFingerprint is included.

Errors

Status	Description
`400`	Invalid page or limit parameter
`401`	Missing or invalid JWT
`403`	You do not have permission to manage webhooks for this application
`404`	Application not found

What's next

With webhooks configured, see [Get Payment Methods] to understand which payment methods are available for a given currency and amount.

Was this page helpful?