Probar un webhook

POST/v1/webhooks/{id}/test

Para desarrolladores

Descripción

Envía a la URL del webhook un evento de prueba firmado igual que una entrega real, y devuelve el código con que respondió el endpoint y cuánto tardó. Sirve para comprobar que el endpoint recibe la entrega y verifica la firma sin esperar un evento real.

Autenticación

Authorizationbearer tokenheaderobligatorio

API key con scope webhooks:write. Formato: Bearer <API_KEY>.

X-Instance-Slugstringheaderobligatorio

Identificador de su instancia. Ver Autenticación.

Request

Path params:

idintegerobligatorio

Identificador del webhook.

Response

200 OKDevuelve un objeto con los campos que siguen.

status_codeinteger | nullsiempre presente

Código HTTP con que respondió el endpoint. null si no respondió.

duration_msintegersiempre presente

Duración del intento, en milisegundos.

errorstring, enum: `timeout | connection_failed | blocked` | nullsiempre presente

Por qué no hubo respuesta: timeout (más de 10 segundos), connection_failed, o blocked si la URL ya no resuelve a una dirección pública. null si el endpoint respondió.

request_headersobjectsiempre presente

Headers con los que se envió la prueba, incluida webhook-signature. Esa firma es un HMAC sobre el body, no el secreto de firma: es el valor que su receptor debe reproducir.

request_bodystringsiempre presente

Body exacto que se envió, tal cual viajó y se firmó.

response_headersobjectsiempre presente

Headers con los que respondió el endpoint. Vacío si no respondió.

response_bodystring | nullsiempre presente

Body con el que respondió el endpoint. null si no respondió.

response_truncatedbooleansiempre presente

true cuando la respuesta superó el límite de lectura y llega recortada.

Notas

• Un 200 de este endpoint no significa que la prueba haya sido exitosa: el resultado está en status_code y error.
• La respuesta trae el intercambio completo para que pueda depurar sin instrumentar su endpoint: lo que se envió, con los headers y el body tal cual se firmaron, y lo que respondió su endpoint. Si su endpoint rechaza la firma, el motivo viaja en response_body.
• Del body de la respuesta se leen hasta 64 KiB; lo que exceda llega recortado y response_truncated queda en true.

Errores

Código	Cuándo
404	El webhook no existe en la instancia (webhook_not_found).
409	El webhook no tiene secreto de firma (webhook_secret_missing). Para resolverlo, rote el secreto con POST /v1/webhooks/{id}/rotate-secret.

Detalle completo en Errores genéricos: not-found y conflict.

Notas

• La entrega lleva un único evento de tipo webhook.test con data vacío. Ver Evento de prueba.
• En las 24 horas que siguen a una rotación del secreto de firma, la prueba lleva las dos firmas, igual que una entrega real: sirve para comprobar que el endpoint ya acepta el secreto nuevo. Ver Rotar el secreto.
• No se reintenta y no modifica el estado de entregas del webhook.
• Funciona también con el webhook pausado.

Request

curl -X POST "https://$API_HOST/v1/webhooks/3/test" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG"

Response

{
"status_code": 204,
"duration_ms": 183,
"error": null,
"request_headers": {
  "content-type": "application/json",
  "webhook-id": "msg_2f1c8a1b9d4e4f7a8c3b5e6d7a8b9c0d",
  "webhook-timestamp": "1790197475",
  "webhook-signature": "v1,r3nRyUrjQj4K4q3/2Y1fxSIqg2i64EOgrPU2lJ9Q03E="
},
"request_body": "{\"events\":[{\"id\":\"evt_3385874cfc3e42b9a3e4d2b876e568f4\",\"type\":\"webhook.test\",\"timestamp\":\"2026-09-23T21:04:35.450Z\",\"data\":{}}]}",
"response_headers": {
  "content-type": "application/json",
  "content-length": "22"
},
"response_body": "{\"status\":\"received\"}",
"response_truncated": false
}