Skip to main content

Webhook configuration

Webhooks provide real-time notifications about verification session status changes. Instead of polling the API, you register an endpoint URL to which the DPay HUB sends events as soon as they occur.

POST/api/v1/webhooksComplete contract: parameters, one-time secret and response codes.Full contract in the API Reference GET/api/v1/webhooksThe tenant's registered endpoints and their current state.Full contract in the API Reference

Registering an endpoint​

POST /api/v1/webhooks
curl -X POST https://hub.dpay.pl/api/v1/webhooks \
  -H "Authorization: Bearer deid_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://twoja-strona.pl/webhooks/dpay",
    "events": ["verification.completed", "verification.failed"],
    "description": "Production endpoint"
  }'

Parameters​

FieldTypeRequiredDescription
urlstring (URL)YesYour endpoint URL; HTTPS is required in production
eventsarrayYesEvent list, or ["*"] for all events
descriptionstringNoEndpoint description displayed in the panel

Response (201)​

{
  "data": {
    "id": "wh-uuid",
    "url": "https://twoja-strona.pl/webhooks/dpay",
    "events": ["verification.completed", "verification.failed"],
    "description": "Production endpoint",
    "is_active": true,
    "failure_count": 0,
    "last_triggered_at": null,
    "last_success_at": null,
    "last_failure_at": null,
    "disabled_at": null,
    "created_at": "2026-04-07T10:00:00+00:00",
    "updated_at": "2026-04-07T10:00:00+00:00"
  },
  "meta": {
    "secret": "whsec_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6"
  }
}
One-time HMAC secret

The meta.secret field is returned only once, in the response to POST /webhooks. Store it securely, for example in a secrets vault. It cannot be retrieved again. If you lose the secret, you must create a new webhook.

The secret is used to verify webhook authenticity. See HMAC signature.

Updating an endpoint​

PATCH /api/v1/webhooks/{id}

This is a partial update: send only the fields you want to change.

curl -X PATCH https://hub.dpay.pl/api/v1/webhooks/{id} \
  -H "Authorization: Bearer deid_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

Updatable fields​

FieldDescription
urlNew endpoint URL
eventsNew subscribed event list
descriptionNew description
is_activeEnable or disable the endpoint (true/false)

Listing endpoints​

curl https://hub.dpay.pl/api/v1/webhooks \
  -H "Authorization: Bearer deid_live_xxx"

Returns all webhook endpoints registered for the tenant.

Endpoint details​

curl https://hub.dpay.pl/api/v1/webhooks/{id} \
  -H "Authorization: Bearer deid_live_xxx"

Sending a test payload​

POST /api/v1/webhooks/{id}/test

Sends an asynchronous test payload with the verification.test event type to the registered endpoint. This is ideal for checking the configuration without creating a real session.

curl -X POST https://hub.dpay.pl/api/v1/webhooks/{id}/test \
  -H "Authorization: Bearer deid_live_xxx"

Deleting an endpoint​

DELETE /api/v1/webhooks/{id}
curl -X DELETE https://hub.dpay.pl/api/v1/webhooks/{id} \
  -H "Authorization: Bearer deid_live_xxx"

Returns 204 No Content on success.

Endpoint requirements​

  • HTTPS is required in production; HTTP is allowed only in the sandbox
  • A 2xx response must be returned within 10 seconds, or the webhook is retried; see Retry policy
  • Idempotency is required because the endpoint may receive the same event more than once during retries
  • Signature verification is mandatory: always verify X-Signature; see HMAC signature

Next steps​

Last updated on