webhooks

Version 0.1.06 opérations

Webhook endpoints of the organisation (secret hints only)

GET/organisations/{id}/webhooksClé API

Paramètres

idstringpathobligatoire

Réponses

200
- idstring (uuid)obligatoire
- organisationIdstring (uuid)obligatoire
- paymentAccountIdstring (uuid) | nullobligatoire
- urlstringobligatoire
- descriptionstring | nullobligatoire
- eventsstring[]obligatoire
  Empty means every event
- secretHintstringobligatoire
  Last four characters of the secret
- statusstringobligatoire
  - enum: "active", "disabled"
- disabledAtstring (date-time) | nullobligatoire
- createdAtstring (date-time)obligatoire
- updatedAtstring (date-time)obligatoire

Exemples de code

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

Exemple : 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}/webhooksClé API

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

Paramètres

idstringpathobligatoire

Corps de la requête application/json

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

Réponses

201
- idstring (uuid)obligatoire
- organisationIdstring (uuid)obligatoire
- paymentAccountIdstring (uuid) | nullobligatoire
- urlstringobligatoire
- descriptionstring | nullobligatoire
- eventsstring[]obligatoire
  Empty means every event
- secretHintstringobligatoire
  Last four characters of the secret
- statusstringobligatoire
  - enum: "active", "disabled"
- disabledAtstring (date-time) | nullobligatoire
- createdAtstring (date-time)obligatoire
- updatedAtstring (date-time)obligatoire
- secretstringobligatoire
  The signing secret, shown once and never stored in clear

Exemples de code

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"
}'

Exemple : corps de la requête

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

Exemple : 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}Clé API

Paramètres

idstringpathobligatoire
endpointIdstringpathobligatoire

Réponses

200
- idstring (uuid)obligatoire
- organisationIdstring (uuid)obligatoire
- paymentAccountIdstring (uuid) | nullobligatoire
- urlstringobligatoire
- descriptionstring | nullobligatoire
- eventsstring[]obligatoire
  Empty means every event
- secretHintstringobligatoire
  Last four characters of the secret
- statusstringobligatoire
  - enum: "active", "disabled"
- disabledAtstring (date-time) | nullobligatoire
- createdAtstring (date-time)obligatoire
- updatedAtstring (date-time)obligatoire

Exemples de code

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

Exemple : 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}Clé API

Paramètres

idstringpathobligatoire
endpointIdstringpathobligatoire

Réponses

200
- idstring (uuid)obligatoire
- organisationIdstring (uuid)obligatoire
- paymentAccountIdstring (uuid) | nullobligatoire
- urlstringobligatoire
- descriptionstring | nullobligatoire
- eventsstring[]obligatoire
  Empty means every event
- secretHintstringobligatoire
  Last four characters of the secret
- statusstringobligatoire
  - enum: "active", "disabled"
- disabledAtstring (date-time) | nullobligatoire
- createdAtstring (date-time)obligatoire
- updatedAtstring (date-time)obligatoire
409webhook_endpoint_disabled

Exemples de code

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

Exemple : 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}/deliveriesClé API

Paramètres

idstringpathobligatoire
endpointIdstringpathobligatoire
cursoranyquery
limitintegerquery
- max: 200
- default: 50
statusstringquery
- enum: "pending", "delivered", "failed"

Réponses

200
- itemsWebhookDeliveryDto[]obligatoire
  - idstring (uuid)obligatoire
  - endpointIdstring (uuid)obligatoire
  - paymentIdstring (uuid)obligatoire
  - eventIdstring (uuid)obligatoire
  - eventTypestringobligatoire
    - enum: "payment.succeeded", "payment.failed", "payment.expired", "payment.canceled", "attempt.duplicate_success"
  - urlstringobligatoire
  - statusstringobligatoire
    - enum: "pending", "delivered", "failed"
  - attemptsnumberobligatoire
  - lastStatusCodenumber | nullobligatoire
  - lastErrorstring | nullobligatoire
  - lastAttemptAtstring (date-time) | nullobligatoire
  - deliveredAtstring (date-time) | nullobligatoire
  - lastOutcomestring | nullobligatoire
    - 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) | nullobligatoire
  - manualTriesnumberobligatoire
  - createdAtstring (date-time)obligatoire
- nextCursorstring | nullobligatoire

Exemples de code

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

Exemple : 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}/retryClé API

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.

Paramètres

idstringpathobligatoire
deliveryIdstringpathobligatoire

Réponses

200
- idstring (uuid)obligatoire
- endpointIdstring (uuid)obligatoire
- paymentIdstring (uuid)obligatoire
- eventIdstring (uuid)obligatoire
- eventTypestringobligatoire
  - enum: "payment.succeeded", "payment.failed", "payment.expired", "payment.canceled", "attempt.duplicate_success"
- urlstringobligatoire
- statusstringobligatoire
  - enum: "pending", "delivered", "failed"
- attemptsnumberobligatoire
- lastStatusCodenumber | nullobligatoire
- lastErrorstring | nullobligatoire
- lastAttemptAtstring (date-time) | nullobligatoire
- deliveredAtstring (date-time) | nullobligatoire
- lastOutcomestring | nullobligatoire
  - 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) | nullobligatoire
- manualTriesnumberobligatoire
- createdAtstring (date-time)obligatoire
409webhook_delivery_pending

Exemples de code

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

Exemple : 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"
}