Aller au contenu
DOTWICK

Enregistrer un endpoint

POST/v1/webhooks

Enregistrer

Les admins enregistrent les endpoints dans l’application sous Settings → API → Webhooks, ou via l’API avec une clé qui a webhooks:write. L’URL doit être en https sur un nom d’hôte public. Un espace de travail compte jusqu’à 10 endpoints ; les webhooks sont inclus dans Pro, Business et Enterprise.

La réponse contient le secret de l’endpoint (whsec_…) une seule fois, avec secretAlreadyShown: false. Un nouvel essai avec le même Idempotency-Key renvoie le même endpoint avec secret: null et secretAlreadyShown: true (voir Idempotence). Les admins peuvent afficher à nouveau le secret dans l’application, et le renouveler : l’ancien secret continue de signer à côté du nouveau jusqu’à 24 heures.

requêtePOST /v1/webhooks
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"  }'
réponse201 Createdle secret n’est renvoyé qu’une fois ; un rejeu répond secret: null
{  "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}

Envoyer un événement de test

Un événement webhook.test est envoyé à l’endpoint quels que soient ses abonnements, même s’il est désactivé, pour que vous puissiez vérifier votre code de vérification.

requêtePOST /v1/webhooks/whe_3k8m2q9x7c4v1b6n/test
curl -X POST https://api.dotwick.com/v1/webhooks/whe_3k8m2q9x7c4v1b6n/test \  -H "Authorization: Bearer sk_live_…" \  -H "Idempotency-Key: fleet-dashboard-test-1"
réponse202 Accepted
{  "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}

À quoi ressemble un envoi

Un POST avec l’événement comme corps JSON et ces en-têtes. L’id du corps et l’en-tête webhook-id sont le même identifiant d’événement, identique à chaque nouvel essai et chaque renvoi : utilisez-le pour ignorer les doublons.

webhook-idL’identifiant de l’événement (evt_…). Le même à chaque nouvel essai : dédoublonnez dessus.
webhook-timestampSecondes Unix de cette tentative.
webhook-signaturev1,<signature base64>, deux séparées par une espace pendant une rotation.
dotwick-event-typeLe type d’événement, pour que vous puissiez router avant d’analyser.
dotwick-delivery-idL’envoi (whd_…), tel qu’affiché dans le journal des envois.
dotwick-attempt1 pour la première tentative, puis 2, 3…
content-typeapplication/json
user-agentDotwick-Webhooks/1.0 (+https://dotwick.com/docs/webhooks)

Nouveaux essais

Toute réponse autre qu’un 2xx dans les 10 secondes est un échec, tout comme une redirection : nous ne les suivons pas. Nous réessayons après 5 s,1 min,5 min,30 min,1 h,2 h,4 h,8 h et 8 h (10 tentatives sur environ 24 heures, chaque attente à ±10 %), et nous respectons un Retry-After plus long sur 429 et 503. L’envoi est ensuite marqué comme échoué.

Endpoints en échec

Quand les envois vers un endpoint échouent depuis 24 heures d’affilée, son créateur et les admins de l’espace de travail reçoivent un e-mail. Après 3 jours d’échecs (et au moins 10 tentatives échouées), l’endpoint est désactivé et ils reçoivent un nouvel e-mail. Un endpoint qui répond 410 Gone est désactivé immédiatement.

Tant qu’un endpoint est désactivé, aucun nouvel événement n’est enregistré pour lui. Corrigez-le, envoyez un événement de test, puis réactivez-le avec PATCH /v1/webhooks/{id} et { "enabled": true }.

Renvoyer et rattraper

Chaque tentative est journalisée pendant 30 jours avec les en-têtes envoyés et ce que votre serveur a répondu (envois scan.created réussis pendant 7 jours). Renvoyez un envoi avec POST /v1/webhooks/{id}/deliveries/{deliveryId}/redeliver, ou tous les envois échoués depuis une date avec POST /v1/webhooks/{id}/recover (1 000 par appel).

Les envois ne sont pas ordonnés : deux modifications d’un même code peuvent arriver dans n’importe quel ordre. Comparez le createdAt de l’événement, ou récupérez l’objet, quand l’ordre compte.