Een endpoint registreren

Registreren

Beheerders registreren endpoints in de app onder Settings → API → Webhooks, of via de API met een sleutel met webhooks:write. De URL moet https zijn op een openbare hostnaam. Een werkruimte heeft tot 10 endpoints; webhooks zitten in Pro, Business en Enterprise.

Het antwoord bevat het geheim van het endpoint (whsec_…) één keer, met secretAlreadyShown: false. Een nieuwe poging met dezelfde Idempotency-Key antwoordt met hetzelfde endpoint met secret: null en secretAlreadyShown: true (zie Idempotentie). Beheerders kunnen het geheim in de app opnieuw tonen en roteren: het oude geheim blijft naast het nieuwe tot 24 uur ondertekenen.

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}

Stuur een testgebeurtenis

Een webhook.test-gebeurtenis gaat naar het endpoint, ongeacht waarop het is geabonneerd en zelfs als het uit staat, zodat je je verificatiecode kunt controleren.

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}

Hoe een levering eruitziet

Een POST met de gebeurtenis als JSON-body en deze headers. De id in de body en de webhook-id-header zijn dezelfde gebeurtenis-id, identiek bij elke nieuwe poging en herlevering: gebruik hem om duplicaten te negeren.

Nieuwe pogingen

Alles behalve een 2xx binnen 10 seconden is een mislukking, en een redirect ook: die volgen we niet. We proberen opnieuw na 5 s, 1 min, 5 min, 30 min, 1 h, 2 h, 4 h, 8 h en 8 h: 10 pogingen in ongeveer 24 uur, elke wachttijd ±10%, en we respecteren een langere Retry-After bij 429 en 503. Daarna wordt de levering als mislukt gemarkeerd.

Falende endpoints

Als leveringen aan een endpoint 24 uur achter elkaar zijn mislukt, krijgen de maker en de beheerders van de werkruimte een e-mail. Na 3 dagen mislukkingen (en minstens 10 mislukte pogingen) wordt het endpoint uitgezet en krijgen ze opnieuw een e-mail. Een endpoint dat 410 Gone antwoordt, wordt meteen uitgezet.

Zolang een endpoint uit staat, worden er geen nieuwe gebeurtenissen voor vastgelegd. Los het op, stuur een testgebeurtenis en zet het weer aan met PATCH /v1/webhooks/{id} en { "enabled": true }.

Opnieuw leveren en herstellen

Elke poging wordt 30 dagen bewaard met de headers die we stuurden en wat je server antwoordde (geslaagde scan.created-leveringen 7 dagen). Stuur één levering opnieuw met POST /v1/webhooks/{id}/deliveries/{deliveryId}/redeliver, of elke mislukte levering sinds een datum met POST /v1/webhooks/{id}/recover (1.000 per aanroep).

Leveringen zijn niet geordend: twee wijzigingen aan één code kunnen in willekeurige volgorde aankomen. Vergelijk het createdAt van de gebeurtenis, of haal het object op, als de volgorde ertoe doet.