Registra un endpoint

Registra

Gli amministratori registrano gli endpoint nell’app in Settings → API → Webhooks, o tramite l’API con una chiave che ha webhooks:write. L’URL deve essere https su un nome host pubblico. Uno spazio di lavoro ha fino a 10 endpoint; i webhook sono inclusi in Pro, Business ed Enterprise.

La risposta riporta il segreto dell’endpoint (whsec_…) una sola volta, con secretAlreadyShown: false. Un nuovo tentativo con lo stesso Idempotency-Key risponde con lo stesso endpoint con secret: null e secretAlreadyShown: true (vedi Idempotenza). Gli amministratori possono rivedere il segreto nell’app e ruotarlo: il vecchio segreto continua a firmare accanto al nuovo per un massimo di 24 ore.

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}

Invia un evento di prova

Un evento webhook.test arriva all’endpoint qualunque cosa sottoscriva, anche se è disattivato, così puoi verificare il tuo codice di verifica.

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}

Come appare una consegna

Un POST con l’evento come corpo JSON e questi header. L’id del corpo e l’header webhook-id sono lo stesso ID evento, identico a ogni nuovo tentativo e riconsegna: usalo per ignorare i duplicati.

Nuovi tentativi

Tutto ciò che non è un 2xx entro 10 secondi è un errore, così come un reindirizzamento: non li seguiamo. Ritentiamo dopo 5 s, 1 min, 5 min, 30 min, 1 h, 2 h, 4 h, 8 h e 8 h: 10 tentativi in circa 24 ore, ogni attesa ±10%, e rispettiamo un Retry-After più lungo su 429 e 503. Poi la consegna viene segnata come non riuscita.

Endpoint che falliscono

Quando le consegne a un endpoint falliscono da 24 ore di fila, il suo creatore e gli amministratori dello spazio di lavoro ricevono un’email. Dopo 3 giorni di errori (e almeno 10 tentativi falliti) l’endpoint viene disattivato e ricevono un’altra email. Un endpoint che risponde 410 Gone viene disattivato subito.

Finché un endpoint è disattivato, per lui non vengono registrati nuovi eventi. Correggilo, invia un evento di prova, poi riattivalo con PATCH /v1/webhooks/{id} e { "enabled": true }.

Riconsegna e recupero

Ogni tentativo è registrato per 30 giorni con gli header che abbiamo inviato e ciò che il tuo server ha risposto (le consegne scan.created riuscite per 7 giorni). Invia di nuovo una consegna con POST /v1/webhooks/{id}/deliveries/{deliveryId}/redeliver, oppure ogni consegna fallita da una data con POST /v1/webhooks/{id}/recover (1000 per chiamata).

Le consegne non sono ordinate: due modifiche allo stesso codice possono arrivare in un ordine qualsiasi. Confronta il createdAt dell’evento, o recupera l’oggetto, quando l’ordine conta.