webhooks

Version 0.1.06 operations

Webhook endpoints of the organisation (secret hints only)

GET/organisations/{id}/webhooksAPI key

Parameters

idstringpathrequired

Responses

200
- idstring (uuid)required
- organisationIdstring (uuid)required
- paymentAccountIdstring (uuid) | nullrequired
- urlstringrequired
- descriptionstring | nullrequired
- eventsstring[]required
  Empty means every event
- secretHintstringrequired
  Last four characters of the secret
- statusstringrequired
  - enum: "active", "disabled"
- disabledAtstring (date-time) | nullrequired
- createdAtstring (date-time)required
- updatedAtstring (date-time)required

Code samples

curl -X GET "$KONNECT_API_URL/organisations/id/webhooks" \
  -H "x-api-key: $KONNECT_API_KEY"

Example: 200

[
  {
    "id": "id",
    "organisationId": "org_01J9Z3K4EXAMPLE0000000000",
    "paymentAccountId": "paymentAccountId",
    "url": "url",
    "description": "description",
    "events": [
      "payment.succeeded"
    ],
    "secretHint": "****ab12",
    "status": "active",
    "disabledAt": "2026-10-01T09:30:00.000Z",
    "createdAt": "2026-10-01T09:30:00.000Z",
    "updatedAt": "2026-10-01T09:30:00.000Z"
  }
]

Register a webhook endpoint; the signing secret is returned once

POST/organisations/{id}/webhooksAPI key

Deliveries are signed with HMAC SHA-256 (Konnect-Signature: t=<unix>,v1=<hex> over "<t>.<raw body>"), see the developer portal.

Parameters

idstringpathrequired

Request body application/json

urlstringrequired
paymentAccountIdstring (uuid)
One payment account; every account when omitted
eventsstring[]
Every event when omitted
descriptionstring
- maxLength: 120

Responses

201
- idstring (uuid)required
- organisationIdstring (uuid)required
- paymentAccountIdstring (uuid) | nullrequired
- urlstringrequired
- descriptionstring | nullrequired
- eventsstring[]required
  Empty means every event
- secretHintstringrequired
  Last four characters of the secret
- statusstringrequired
  - enum: "active", "disabled"
- disabledAtstring (date-time) | nullrequired
- createdAtstring (date-time)required
- updatedAtstring (date-time)required
- secretstringrequired
  The signing secret, shown once and never stored in clear

Code samples

curl -X POST "$KONNECT_API_URL/organisations/id/webhooks" \
  -H "x-api-key: $KONNECT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://shop.example.test/konnect/webhook",
  "paymentAccountId": "paymentAccountId",
  "events": [
    "payment.succeeded"
  ],
  "description": "description"
}'

Example: request body

{
  "url": "https://shop.example.test/konnect/webhook",
  "paymentAccountId": "paymentAccountId",
  "events": [
    "payment.succeeded"
  ],
  "description": "description"
}

Example: 201

{
  "id": "id",
  "organisationId": "org_01J9Z3K4EXAMPLE0000000000",
  "paymentAccountId": "paymentAccountId",
  "url": "url",
  "description": "description",
  "events": [
    "payment.succeeded"
  ],
  "secretHint": "****ab12",
  "status": "active",
  "disabledAt": "2026-10-01T09:30:00.000Z",
  "createdAt": "2026-10-01T09:30:00.000Z",
  "updatedAt": "2026-10-01T09:30:00.000Z",
  "secret": "whsec_..."
}

One webhook endpoint

GET/organisations/{id}/webhooks/{endpointId}API key

Parameters

idstringpathrequired
endpointIdstringpathrequired

Responses

200
- idstring (uuid)required
- organisationIdstring (uuid)required
- paymentAccountIdstring (uuid) | nullrequired
- urlstringrequired
- descriptionstring | nullrequired
- eventsstring[]required
  Empty means every event
- secretHintstringrequired
  Last four characters of the secret
- statusstringrequired
  - enum: "active", "disabled"
- disabledAtstring (date-time) | nullrequired
- createdAtstring (date-time)required
- updatedAtstring (date-time)required

Code samples

curl -X GET "$KONNECT_API_URL/organisations/id/webhooks/endpointId" \
  -H "x-api-key: $KONNECT_API_KEY"

Example: 200

{
  "id": "id",
  "organisationId": "org_01J9Z3K4EXAMPLE0000000000",
  "paymentAccountId": "paymentAccountId",
  "url": "url",
  "description": "description",
  "events": [
    "payment.succeeded"
  ],
  "secretHint": "****ab12",
  "status": "active",
  "disabledAt": "2026-10-01T09:30:00.000Z",
  "createdAt": "2026-10-01T09:30:00.000Z",
  "updatedAt": "2026-10-01T09:30:00.000Z"
}

Disable an endpoint (terminal; its delivery log stays)

DELETE/organisations/{id}/webhooks/{endpointId}API key

Parameters

idstringpathrequired
endpointIdstringpathrequired

Responses

200
- idstring (uuid)required
- organisationIdstring (uuid)required
- paymentAccountIdstring (uuid) | nullrequired
- urlstringrequired
- descriptionstring | nullrequired
- eventsstring[]required
  Empty means every event
- secretHintstringrequired
  Last four characters of the secret
- statusstringrequired
  - enum: "active", "disabled"
- disabledAtstring (date-time) | nullrequired
- createdAtstring (date-time)required
- updatedAtstring (date-time)required
409webhook_endpoint_disabled

Code samples

curl -X DELETE "$KONNECT_API_URL/organisations/id/webhooks/endpointId" \
  -H "x-api-key: $KONNECT_API_KEY"

Example: 200

{
  "id": "id",
  "organisationId": "org_01J9Z3K4EXAMPLE0000000000",
  "paymentAccountId": "paymentAccountId",
  "url": "url",
  "description": "description",
  "events": [
    "payment.succeeded"
  ],
  "secretHint": "****ab12",
  "status": "active",
  "disabledAt": "2026-10-01T09:30:00.000Z",
  "createdAt": "2026-10-01T09:30:00.000Z",
  "updatedAt": "2026-10-01T09:30:00.000Z"
}

Delivery log of an endpoint, newest first

GET/organisations/{id}/webhooks/{endpointId}/deliveriesAPI key

Parameters

idstringpathrequired
endpointIdstringpathrequired
cursoranyquery
limitintegerquery
- max: 200
- default: 50
statusstringquery
- enum: "pending", "delivered", "failed"

Responses

200
- itemsWebhookDeliveryDto[]required
  - idstring (uuid)required
  - endpointIdstring (uuid)required
  - paymentIdstring (uuid)required
  - eventIdstring (uuid)required
  - eventTypestringrequired
    - enum: "payment.succeeded", "payment.failed", "payment.expired", "payment.canceled", "attempt.duplicate_success"
  - urlstringrequired
  - statusstringrequired
    - enum: "pending", "delivered", "failed"
  - attemptsnumberrequired
  - lastStatusCodenumber | nullrequired
  - lastErrorstring | nullrequired
  - lastAttemptAtstring (date-time) | nullrequired
  - deliveredAtstring (date-time) | nullrequired
  - lastOutcomestring | nullrequired
    - enum: "delivered", "http_4xx", "http_5xx", "timeout", "connection_refused", "dns_error", "tls_error", "redirect_not_followed", "response_too_large", "invalid_url_or_blocked", "other"
  - nextRetryAtstring (date-time) | nullrequired
  - manualTriesnumberrequired
  - createdAtstring (date-time)required
- nextCursorstring | nullrequired

Code samples

curl -X GET "$KONNECT_API_URL/organisations/id/webhooks/endpointId/deliveries" \
  -H "x-api-key: $KONNECT_API_KEY"

Example: 200

{
  "items": [
    {
      "id": "id",
      "endpointId": "endpointId",
      "paymentId": "665f1c2e8b3a4d0012ab34cd",
      "eventId": "eventId",
      "eventType": "payment.succeeded",
      "url": "url",
      "status": "pending",
      "attempts": 1,
      "lastStatusCode": 1,
      "lastError": "lastError",
      "lastAttemptAt": "2026-10-01T09:30:00.000Z",
      "deliveredAt": "2026-10-01T09:30:00.000Z",
      "lastOutcome": "delivered",
      "nextRetryAt": "2026-10-01T09:30:00.000Z",
      "manualTries": 1,
      "createdAt": "2026-10-01T09:30:00.000Z"
    }
  ],
  "nextCursor": "nextCursor"
}

Replay a delivery once (manual try)

POST/organisations/{id}/webhooks/deliveries/{deliveryId}/retryAPI key

One immediate try of a delivery that is not waiting for a try (failed or delivered). Audited, recorded on the payment timeline as a manual try, never counted in the six automatic tries.

Parameters

idstringpathrequired
deliveryIdstringpathrequired

Responses

200
- idstring (uuid)required
- endpointIdstring (uuid)required
- paymentIdstring (uuid)required
- eventIdstring (uuid)required
- eventTypestringrequired
  - enum: "payment.succeeded", "payment.failed", "payment.expired", "payment.canceled", "attempt.duplicate_success"
- urlstringrequired
- statusstringrequired
  - enum: "pending", "delivered", "failed"
- attemptsnumberrequired
- lastStatusCodenumber | nullrequired
- lastErrorstring | nullrequired
- lastAttemptAtstring (date-time) | nullrequired
- deliveredAtstring (date-time) | nullrequired
- lastOutcomestring | nullrequired
  - enum: "delivered", "http_4xx", "http_5xx", "timeout", "connection_refused", "dns_error", "tls_error", "redirect_not_followed", "response_too_large", "invalid_url_or_blocked", "other"
- nextRetryAtstring (date-time) | nullrequired
- manualTriesnumberrequired
- createdAtstring (date-time)required
409webhook_delivery_pending

Code samples

curl -X POST "$KONNECT_API_URL/organisations/id/webhooks/deliveries/deliveryId/retry" \
  -H "x-api-key: $KONNECT_API_KEY"

Example: 200

{
  "id": "id",
  "endpointId": "endpointId",
  "paymentId": "665f1c2e8b3a4d0012ab34cd",
  "eventId": "eventId",
  "eventType": "payment.succeeded",
  "url": "url",
  "status": "pending",
  "attempts": 1,
  "lastStatusCode": 1,
  "lastError": "lastError",
  "lastAttemptAt": "2026-10-01T09:30:00.000Z",
  "deliveredAt": "2026-10-01T09:30:00.000Z",
  "lastOutcome": "delivered",
  "nextRetryAt": "2026-10-01T09:30:00.000Z",
  "manualTries": 1,
  "createdAt": "2026-10-01T09:30:00.000Z"
}