Zarejestruj endpoint

Rejestracja

Administratorzy rejestrują endpointy w aplikacji w Settings → API → Webhooks albo przez API kluczem z webhooks:write. URL musi być https na publicznej nazwie hosta. Obszar roboczy ma do 10 endpointów; webhooki są w planach Pro, Business i Enterprise.

Odpowiedź zawiera sekret endpointu (whsec_…) jeden raz, z secretAlreadyShown: false. Ponowienie z tym samym Idempotency-Key odpowiada tym samym endpointem z secret: null i secretAlreadyShown: true (patrz Idempotentność). Administratorzy mogą ponownie wyświetlić sekret w aplikacji i go zrotować: stary sekret nadal podpisuje obok nowego przez maksymalnie 24 godz.

curl -X POST https://api.dotwick.com/v1/webhooks \  -H "Authorization: Bearer sk_live_…" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: fleet-dashboard-hook" \  -d '{    "url": "https://hooks.example.com/dotwick",    "events": [      "scan.created",      "code.updated",      "bulk.completed"    ],    "description": "Fleet dashboard"  }'

{  "id": "whe_3k8m2q9x7c4v1b6n",  "url": "https://hooks.example.com/dotwick",  "events": [    "scan.created",    "code.updated",    "bulk.completed"  ],  "description": "Fleet dashboard",  "enabled": true,  "disabledReason": null,  "disabledAt": null,  "apiVersion": "2026-09-01",  "createdAt": "2026-09-12T14:03:51.000Z",  "updatedAt": "2026-09-12T14:03:51.000Z",  "lastEventType": null,  "lastStatusCode": null,  "lastDeliveryAt": null,  "lastSuccessAt": null,  "failureCount": 0,  "failingSince": null,  "previousSecretExpiresAt": null,  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw",  "secretAlreadyShown": false}

Wyślij zdarzenie testowe

Zdarzenie webhook.test trafia do endpointu niezależnie od subskrybowanych zdarzeń, nawet gdy jest wyłączony, więc możesz sprawdzić swój kod weryfikacji.

curl -X POST https://api.dotwick.com/v1/webhooks/whe_3k8m2q9x7c4v1b6n/test \  -H "Authorization: Bearer sk_live_…" \  -H "Idempotency-Key: fleet-dashboard-test-1"

{  "id": "whd_7t2p9w4k1m8x3c6v",  "endpointId": "whe_3k8m2q9x7c4v1b6n",  "eventId": "evt_1q2w3e4r5t6y7u8i",  "eventType": "webhook.test",  "status": "pending",  "attempts": 0,  "lastStatusCode": null,  "lastError": null,  "lastAttemptAt": null,  "nextAttemptAt": "2026-09-12T14:03:51.000Z",  "createdAt": "2026-09-12T14:03:51.000Z",  "deliveredAt": null}

Jak wygląda dostawa

Żądanie POST ze zdarzeniem jako ciałem JSON i tymi nagłówkami. id w ciele i nagłówek webhook-id to ten sam identyfikator zdarzenia, identyczny przy każdym ponowieniu i ponownej dostawie: użyj go do ignorowania duplikatów.

Ponowienia

Wszystko poza kodem 2xx w ciągu 10 sekund to niepowodzenie, podobnie jak przekierowanie: nie podążamy za nimi. Ponawiamy po 5 s, 1 min, 5 min, 30 min, 1 h, 2 h, 4 h, 8 h i 8 h: 10 prób w ciągu około 24 godz., każde oczekiwanie ±10%, i respektujemy dłuższy Retry-After przy 429 i 503. Potem dostarczenie jest oznaczane jako nieudane.

Endpointy z błędami

Gdy dostawy do endpointu zawodzą przez 24 godz. z rzędu, jego twórca i administratorzy obszaru roboczego dostają e-mail. Po 3 dniach błędów (i co najmniej 10 nieudanych próbach) endpoint zostaje wyłączony i dostają kolejny e-mail. Endpoint odpowiadający 410 Gone jest wyłączany od razu.

Gdy endpoint jest wyłączony, nie rejestrujemy dla niego nowych zdarzeń. Napraw go, wyślij zdarzenie testowe, a potem włącz go ponownie przez PATCH /v1/webhooks/{id} i { "enabled": true }.

Ponowna dostawa i odzyskiwanie

Każda próba jest zapisywana przez 30 dni wraz z wysłanymi nagłówkami i odpowiedzią Twojego serwera (udane dostawy scan.created przez 7 dni). Wyślij jedną dostawę ponownie przez POST /v1/webhooks/{id}/deliveries/{deliveryId}/redeliver albo każdą nieudaną dostawę od danej daty przez POST /v1/webhooks/{id}/recover (1000 na wywołanie).

Dostawy nie są uporządkowane: dwie zmiany jednego kodu mogą dotrzeć w dowolnej kolejności. Gdy kolejność ma znaczenie, porównaj createdAt zdarzenia albo pobierz obiekt.