POST /v1/webhooks/{id}/test

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 FD.<key_id>.<token>.

X-Instance-Slugstringheaderobligatorio

Request

Path params:

idinteger

Identificador del webhook.

Response

200 OKDevuelve un objeto con los campos que siguen.

status_codeinteger | nullobligatorio

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

duration_msintegerobligatorio

Duración del intento, en milisegundos.

errorstring, enum: `timeout | connection_failed | blocked` | nullobligatorio

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ó.

Nota

Un 200 de este endpoint no significa que la prueba haya sido exitosa: el resultado está en status_code y error.

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). Rotar el secreto lo resuelve.

Detalle completo en Errores genéricos y Errores genéricos.

Notas

• La entrega lleva un único evento de tipo webhook.test con data vacío. Ver Evento de prueba (pendiente de publicación).
• En las 24 horas que siguen a una rotación del secreto, 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 (pendiente de publicación).
• 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
}