Endpunkt registrieren

Registrieren

Admins registrieren Endpunkte in der App unter Settings → API → Webhooks oder über die API mit einem Schlüssel, der webhooks:write hat. Die URL muss https auf einem öffentlichen Hostnamen sein. Ein Arbeitsbereich hat bis zu 10 Endpunkte; Webhooks gibt es in Pro, Business und Enterprise.

Die Antwort enthält das Secret des Endpunkts (whsec_…) einmalig, mit secretAlreadyShown: false. Ein erneuter Versuch mit demselben Idempotency-Key beantwortet denselben Endpunkt mit secret: null und secretAlreadyShown: true (siehe Idempotenz). Admins können das Secret in der App erneut anzeigen und rotieren: Das alte Secret signiert bis zu 24 Stunden neben dem neuen weiter.

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}

Ein Testereignis senden

Ein webhook.test-Ereignis geht an den Endpunkt, egal was er abonniert hat – selbst wenn er ausgeschaltet ist –, damit Sie Ihren Verifizierungscode prüfen können.

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}

Wie eine Zustellung aussieht

Ein POST mit dem Ereignis als JSON-Body und diesen Headern. Die id im Body und der Header webhook-id sind dieselbe Ereignis-ID, bei jedem Retry und jeder erneuten Zustellung identisch: Nutzen Sie sie, um Duplikate zu ignorieren.

Wiederholungen

Alles außer einem 2xx innerhalb von 10 Sekunden ist ein Fehlschlag, ebenso eine Weiterleitung: Wir folgen ihr nicht. Wir wiederholen nach 5 s, 1 Min., 5 Min., 30 Min., 1 Std., 2 Std., 4 Std., 8 Std. und 8 Std. – 10 Versuche über etwa 24 Stunden, jede Wartezeit ±10 % – und beachten ein längeres Retry-After bei 429 und 503. Dann wird die Zustellung als fehlgeschlagen markiert.

Fehlschlagende Endpunkte

Sind Zustellungen an einen Endpunkt 24 Stunden in Folge fehlgeschlagen, erhalten sein Ersteller und die Admins des Arbeitsbereichs eine E-Mail. Nach 3 Tagen Fehlschlägen (und mindestens 10 fehlgeschlagenen Versuchen) wird der Endpunkt ausgeschaltet, und sie erhalten erneut eine E-Mail. Ein Endpunkt, der mit 410 Gone antwortet, wird sofort ausgeschaltet.

Solange ein Endpunkt aus ist, werden für ihn keine neuen Ereignisse aufgezeichnet. Beheben Sie das Problem, senden Sie ein Testereignis und schalten Sie ihn dann mit PATCH /v1/webhooks/{id} und { "enabled": true } wieder ein.

Erneut zustellen und wiederherstellen

Jeder Versuch wird 30 Tage lang protokolliert, mit den gesendeten Headern und der Antwort Ihres Servers (erfolgreiche scan.created-Zustellungen 7 Tage). Senden Sie eine Zustellung erneut mit POST /v1/webhooks/{id}/deliveries/{deliveryId}/redeliver oder jede fehlgeschlagene Zustellung seit einem Datum mit POST /v1/webhooks/{id}/recover (1.000 pro Aufruf).

Zustellungen sind nicht geordnet: Zwei Änderungen an einem Code können in beliebiger Reihenfolge ankommen. Vergleichen Sie das createdAt des Ereignisses oder rufen Sie das Objekt ab, wenn die Reihenfolge zählt.