Webhooks
Recibe un mensaje firmado en cuanto termina una ejecución y deja de consultar para obtener el archivo
Un webhook es una dirección tuya a la que DocTransform llama cada vez que termina una de tus ejecuciones. Piensa en un timbre: en lugar de preguntar una y otra vez si la ejecución ha terminado, esperas, y DocTransform llama cuando está lista. Esa llamada es un mensaje corto llamado evento. Te dice qué ejecución terminó y te da un enlace al archivo.
Crear un webhook
Necesitas una sola cosa: una dirección que empiece por https:// y a la que se pueda llegar desde internet. Una herramienta como Zapier te da una, y tu propio servidor también.
Abre la tarjeta Webhooks
Ve a tu página de cuenta y busca la tarjeta llamada Webhooks. Pulsa Añadir Webhook.
Pega tu dirección
Pégala en Dirección a la que enviar eventos. Terminó una ejecución y Falló una ejecución ya están marcados, y también Para todas las plantillas. Cámbialos solo si lo necesitas.
Guarda y envía una prueba
Pulsa Guardar Webhook y luego Enviar evento de prueba. La respuesta aparece en el Registro de entregas de la misma pantalla, así sabes que funciona antes de una ejecución real.
Copia el secreto de firma
Solo si tu propio código va a comprobar los eventos: bajo Secreto de firma, pulsa Mostrar y luego Copiar. Quien use Zapier, Make o n8n puede saltarse este paso.
Puedes añadir hasta 5 webhooks, igual en todos los planes. Los webhooks se gestionan solo en la página de cuenta, no por la API. Las entregas nunca cuentan para tu cuota.
GET /runs/{id} sigue funcionando y no va a desaparecer. ¿Escribes código? Lee Verificar webhooks. ¿UsasZapier, Make o n8n? Solo necesitas la dirección que te dan esas herramientas.Qué llega
Cada evento es un POST con un cuerpo JSON de tres partes: type, timestamp (cuándo terminó la ejecución) y data. Todas las claves están siempre, y valen null cuando no se aplican, así una herramienta asigna los mismos campos cada vez. Nunca incluye contenido del archivo, columnas, nombres de archivo ni nombres de plantilla: para los detalles, consulta GET /runs/{id}.
run.succeeded se envía cuando el archivo está listo:
{
"type": "run.succeeded",
"timestamp": "2026-09-27T10:15:00Z",
"data": {
"run_id": "run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58",
"template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
"status": "succeeded",
"download_url": "https://doctransform.xyz/api/v1/runs/run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58/download?expires=1790763300&signature=0000000000000000000000000000000000000000000000000000000000000000",
"expires_at": "2026-09-30T10:15:00Z",
"error": null
}
}run.failed se envía cuando una ejecución termina sin archivo. No trae enlace, y error.code es uno de los códigos de error:
{
"type": "run.failed",
"timestamp": "2026-09-27T10:15:00Z",
"data": {
"run_id": "run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58",
"template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
"status": "failed",
"download_url": null,
"expires_at": null,
"error": {
"code": "PIPELINE_FAILED",
"message": "The pipeline failed while running the Template."
}
}
}webhook.test es lo que envía Enviar evento de prueba. Su enlace no funciona, así que ignóralo con if type == "webhook.test":
{
"type": "webhook.test",
"timestamp": "2026-09-27T10:15:00+00:00",
"data": {
"run_id": "run_test",
"template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
"status": "succeeded",
"download_url": "https://doctransform.xyz/api/v1/runs/run_test/download?expires=1790590500&signature=0000000000000000000000000000000000000000000000000000000000000000",
"expires_at": "2026-09-28T10:15:00+00:00",
"error": null
}
}Comprobar que un evento es auténtico
Cualquiera que encuentre tu dirección podría enviarle datos. Cada evento lleva una firma que solo pueden crear DocTransform y tú, así tu código distingue un evento real de uno falso. Verificar webhooks explica cómo, con ejemplos para copiar.
Reintentos y desactivación
Un evento cuenta como entregado solo cuando tu dirección responde con un estado 2xx en menos de 10 segundos. Las redirecciones no se siguen. Cualquier otra cosa se reintenta, así que una caída corta de tu lado no pierde nada. Tras cada intento fallido, DocTransform espera más:
| Tras el intento fallido | Espera antes del siguiente |
|---|---|
| 1 | 1 min |
| 2 | 5 min |
| 3 | 30 min |
| 4 | 2 h |
| 5 | 6 h |
| 6 | 12 h |
| 7 | 24 h |
| 8 | 18 h |
Son 9 intentos en unos 2,6 días (62 h 36 min, más o menos un 10 %). Que se repita un evento que ya tramitaste es normal: mira Evitar repeticiones y duplicados.
Cuando las entregas fallan
El webhook sigue activo y muestra que está fallando. Abre su Registro de entregas para ver cada intento y por qué falló. Recibes un correo tras 24 horas fallando. Cuando tu dirección vuelva a responder, el siguiente intento entrega el evento.
El registro de entregas da a cada intento fallido uno de estos motivos:
| Motivo | En palabras sencillas | Qué hacer |
|---|---|---|
WEBHOOK_UNREACHABLE | No pudimos llegar a tu dirección: no existe, está sin conexión o nos rechazó. | Comprueba que la dirección no tenga errores y que tu receptor esté funcionando. |
WEBHOOK_TIMEOUT | Tu dirección tardó más de 10 segundos en responder. | Responde primero y haz el trabajo lento después. |
WEBHOOK_REJECTED | Tu dirección respondió, pero con un error en vez de un estado 2xx. | Mira el registro de tu receptor para ver por qué dijo que no. |
WEBHOOK_REDIRECTED | Tu dirección nos envió a otra dirección, y eso nunca lo seguimos. | Pega la dirección final en su lugar. |
WEBHOOK_URL_BLOCKED | La dirección apunta a una red privada, así que dejamos de enviarle. | Usa una dirección https pública. Para probar en tu propio ordenador, mira Probar webhooks en local. |
WEBHOOK_SECRET_UNREADABLE | No pudimos leer el secreto de firma del webhook, así que no se envió nada. | Abre el webhook y pulsa Cambiar secreto. |
WEBHOOK_DISABLED | El webhook estaba apagado, así que el evento no se envió. | Pulsa Activar. |
Cuando un webhook se desactiva
Tras 10 intentos fallidos seguidos, repartidos en más de 5 días, el webhook queda Desactivado y recibes un segundo correo. No se envía nada más. Arregla tu dirección y pulsa Activar: te ofrece reenviar las entregas que se detuvieron al desactivarlo, de los últimos 3 días. Una ejecución que terminó mientras el webhook estaba desactivado no se envía: consigue su archivo con GET /runs/{id}/output, o con su enlace de descarga mientras dure. También puedes pulsar Reenviar en una entrega concreta.
Cuando tu dirección responde «desaparecida»
Si tu dirección responde 410 Gone, el webhook se desactiva al instante, porque esa respuesta significa que no va a volver. Pasa a menudo cuando se borra un Zap o un escenario, o se deja apagado. Recupera el receptor y pulsa Activar.
Descargar el archivo
download_url descarga el archivo sin clave de API hasta expires_at. Eso es 3 días después de que terminó la ejecución si un webhook la recibe, y 30 minutos si no, que es también lo que dura GET /runs/{id}/output. Vale null en run.failed y en una entrega enviada cuando el archivo ya caducó, como un Reenviar tardío. Un enlace caducado responde DOWNLOAD_LINK_EXPIRED: vuelve a ejecutar la plantilla.
Probar webhooks en local
DocTransform solo envía a direcciones https públicas, así que localhost se rechaza. Un túnel da a tu servidor local una dirección pública. Este no necesita cuenta:
cloudflared tunnel --url http://localhost:8000Pega en un webhook la dirección que imprime, más tu ruta, y pulsa Enviar evento de prueba. ngrok hace lo mismo. Elimina el webhook cuando termines, porque la dirección del túnel cambia cada vez.
Ver qué pasó
Actividad de la API en tu página de cuenta lista cada petición que hicieron tus claves de API en los últimos 90 días, incluidas las rechazadas. El Registro de entregas de cada webhook muestra todos los intentos con su respuesta y un botón Reenviar. Ambos se unen por el id de la ejecución: pulsa Ver esta ejecución para saltar de uno a otro.