Registrar un endpoint

Registrar

Los administradores registran endpoints en la app, en Settings → API → Webhooks, o a través de la API con una clave que tenga webhooks:write. La URL debe ser https en un nombre de host público. Un espacio de trabajo tiene hasta 10 endpoints; los webhooks están en Pro, Business y Enterprise.

La respuesta incluye el secreto del endpoint (whsec_…) una sola vez, con secretAlreadyShown: false. Un reintento con la misma Idempotency-Key responde con el mismo endpoint con secret: null y secretAlreadyShown: true (consulta Idempotencia). Los administradores pueden volver a mostrar el secreto en la app y rotarlo: el secreto antiguo sigue firmando junto al nuevo hasta 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}

Enviar un evento de prueba

Un evento webhook.test llega al endpoint sea cual sea el evento al que esté suscrito, incluso con el endpoint desactivado, para que puedas comprobar tu código de verificación.

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}

Cómo es una entrega

Un POST con el evento como cuerpo JSON y estas cabeceras. El id del cuerpo y la cabecera webhook-id son el mismo id de evento, idéntico en cada reintento y reenvío: úsalo para ignorar duplicados.

Reintentos

Cualquier cosa que no sea un 2xx en 10 segundos es un fallo, y también lo es una redirección: no las seguimos. Reintentamos tras 5 s, 1 min, 5 min, 30 min, 1 h, 2 h, 4 h, 8 h y 8 h: 10 intentos en unas 24 horas, con una variación de ±10 % en cada espera, y respetamos un Retry-After más largo en 429 y 503. Después, la entrega se marca como fallida.

Endpoints que fallan

Cuando las entregas a un endpoint llevan 24 horas seguidas fallando, quien lo creó y los administradores del espacio de trabajo reciben un correo. Tras 3 días de fallos (y al menos 10 intentos fallidos) el endpoint se desactiva y reciben otro correo. Un endpoint que responde 410 Gone se desactiva de inmediato.

Mientras un endpoint está desactivado, no se registran eventos nuevos para él. Arréglalo, envía un evento de prueba y vuelve a activarlo con PATCH /v1/webhooks/{id} y { "enabled": true }.

Reenviar y recuperar

Cada intento se registra durante 30 días con las cabeceras que enviamos y lo que respondió tu servidor (las entregas correctas de scan.created, durante 7 días). Reenvía una entrega con POST /v1/webhooks/{id}/deliveries/{deliveryId}/redeliver, o todas las entregas fallidas desde una fecha con POST /v1/webhooks/{id}/recover (1000 por llamada).

Las entregas no están ordenadas: dos cambios en un mismo código pueden llegar en cualquier orden. Compara el createdAt del evento, o consulta el objeto, cuando el orden importe.