Registrar um endpoint

Registrar

Os administradores registram endpoints no app em Settings → API → Webhooks, ou pela API com uma chave que tenha webhooks:write. A URL precisa ser https em um nome de host público. Um espaço de trabalho tem até 10 endpoints; os webhooks estão no Pro, no Business e no Enterprise.

A resposta traz o segredo do endpoint (whsec_…) uma única vez, com secretAlreadyShown: false. Uma repetição com o mesmo Idempotency-Key responde o mesmo endpoint com secret: null e secretAlreadyShown: true (veja Idempotência). Os administradores podem mostrar o segredo de novo no app e rotacioná-lo: o segredo antigo continua assinando junto com o novo por até 24 horas.

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}

Envie um evento de teste

Um evento webhook.test chega ao endpoint independentemente do que ele assina, mesmo desligado, para que você confira o seu código de verificação.

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}

Como é uma entrega

Um POST com o evento como corpo JSON e estes cabeçalhos. O id do corpo e o cabeçalho webhook-id são o mesmo ID de evento, idêntico em toda repetição e reentrega: use-o para ignorar duplicatas.

Novas tentativas

Qualquer coisa diferente de um 2xx em 10 segundos é falha, e um redirecionamento também: não os seguimos. Tentamos de novo após 5 s, 1 min, 5 min, 30 min, 1 h, 2 h, 4 h, 8 h e 8 h: 10 tentativas em cerca de 24 horas, cada espera ±10%, e respeitamos um Retry-After maior em 429 e 503. Depois a entrega é marcada como falha.

Endpoints com falha

Quando as entregas a um endpoint falham por 24 horas seguidas, o criador dele e os administradores do espaço de trabalho recebem um e-mail. Depois de 3 dias de falhas (e pelo menos 10 tentativas falhas) o endpoint é desligado e eles recebem outro e-mail. Um endpoint que responde 410 Gone é desligado na hora.

Enquanto um endpoint está desligado, nenhum evento novo é registrado para ele. Corrija-o, envie um evento de teste e ligue-o de novo com PATCH /v1/webhooks/{id} e { "enabled": true }.

Reenviar e recuperar

Cada tentativa fica registrada por 30 dias com os cabeçalhos que enviamos e o que o seu servidor respondeu (entregas scan.created bem-sucedidas por 7 dias). Reenvie uma entrega com POST /v1/webhooks/{id}/deliveries/{deliveryId}/redeliver, ou toda entrega falha desde uma data com POST /v1/webhooks/{id}/recover (1.000 por chamada).

As entregas não são ordenadas: duas mudanças em um código podem chegar em qualquer ordem. Compare o createdAt do evento, ou busque o objeto, quando a ordem importar.