Skip to main content

Konfiguracja webhook

Webhooks umożliwiają otrzymywanie powiadomień w czasie rzeczywistym o zmianach statusu sesji weryfikacyjnych. Zamiast pollować API, rejestrujesz endpoint URL, na który DPay HUB wysyła zdarzenia natychmiast po ich wystąpieniu.

Rejestracja endpointu​

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": "Produkcyjny endpoint"
  }'

Parametry​

PoleTypWymaganeOpis
urlstring (URL)TakURL Twojego endpointu (HTTPS wymagane na produkcji)
eventsarrayTakLista zdarzeń lub ["*"] dla wszystkich
descriptionstringNieOpis endpointu (do panelu)

Odpowiedź (201)​

{
  "data": {
    "id": "wh-uuid",
    "url": "https://twoja-strona.pl/webhooks/dpay",
    "events": ["verification.completed", "verification.failed"],
    "description": "Produkcyjny 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"
  }
}
Secret HMAC - jednorazowy!

Pole meta.secret jest zwracane tylko raz - w odpowiedzi na POST /webhooks. Zapisz je bezpiecznie (np. w secrets vault). Nie będzie dostępne ponownie - jeśli stracisz secret, musisz utworzyć nowy webhook.

Secret służy do weryfikacji autentyczności webhooków - patrz Podpis HMAC.

Aktualizacja endpointu​

PATCH /api/v1/webhooks/{id}

Częściowa aktualizacja - prześlij tylko pola do zmiany.

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

Pola możliwe do aktualizacji​

PoleOpis
urlNowy URL endpointu
eventsNowa lista subskrybowanych zdarzeń
descriptionZmiana opisu
is_activeWłączenie/wyłączenie endpointu (true/false)

Lista endpointów​

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

Zwraca listę wszystkich zarejestrowanych webhook endpointów dla tenanta.

Szczegóły endpointu​

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

Wysyłanie testowego payloadu​

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

Wysyła asynchroniczny testowy payload (zdarzenie typu verification.test) na zarejestrowany endpoint. Idealne do weryfikacji konfiguracji bez konieczności tworzenia rzeczywistej sesji.

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

Usuwanie endpointu​

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

Zwraca 204 No Content przy sukcesie.

Wymagania endpointu​

  • HTTPS wymagane na produkcji (HTTP dozwolone tylko w sandboxie)
  • Odpowiedź 2xx w czasie do 10 sekund - inaczej webhook zostanie ponowiony (patrz Polityka retry)
  • Idempotentność - endpoint może otrzymać to samo zdarzenie wielokrotnie (przy retry)
  • Weryfikacja podpisu - obowiązkowo sprawdzaj X-Signature (patrz Podpis HMAC)

Następne kroki​

Last updated on