Webhooks de aviso
Un segundo canal para el aviso de que una tarea cron ha fallado, junto al correo y nunca en su lugar.
Versión del contrato 1.15.0 La referencia de abajo se lee del contrato OpenAPI, que está escrito en inglés. No se traduce a propósito: traducirlo significaría copiarlo, y una copia acaba divergiendo. Descarga el contrato público (OpenAPI, JSON)
Qué es aquí un webhook
Registras una dirección https; cuando una tarea cron ha fallado de forma definitiva, le mandamos un POST. Slack y Discord leen un solo campo y reciben una línea de texto; cualquier otro destino recibe el JSON que se describe más abajo.
El canal es tuyo y no del espacio de trabajo. Dos personas del mismo equipo tienen dos destinos distintos, y ningún rol — ni siquiera Admin — puede leer el de otro miembro. Una tarea cron que falla debe despertar a quien está de guardia.
Es un canal de más, nunca un canal en lugar de: el correo sigue encendido por omisión, porque si no un webhook que deja de funcionar apagaría los avisos sin decirlo.
Registrar e inspeccionar un canal
Un canal se registra, se enumera y se elimina desde el panel, y esas rutas no están en esta página porque ninguna clave las alcanza. Quieren una sesión y no una clave API, y la asimetría es deliberada: una clave capaz de sustituir la dirección de un webhook podría desviar los avisos del espacio de trabajo a un destino suyo — descubriendo qué tareas cron fallan, y cuándo — mientras quien lo posee sigue viendo un canal que parece configurado.
Ninguna ruta devuelve jamás una dirección, ni siquiera sus últimos caracteres. Lo que identifica un canal en una lista son el nombre que elegiste y el host.
Los eventos que salen
The events that may leave towards an external webhook. There is one, and it is what R29 asks for: "failure notifications".
Plan changes, welcomes and account security events stay out on purpose. A Slack channel is shared and sits outside our perimeter: those events concern a person and their relationship with us, and announcing them in a shared channel would hand them to colleagues who have nothing to do with it. Security is the least obvious of the four — an unauthorised sign-in is *the* thing one would want to know quickly — and it stays out because to be useful it would have to say *what* happened to the account, and that, in a channel, is an invitation.
| Nombre | Tipo | Notas |
|---|---|---|
job_failed |
Qué lleva el cuerpo
La lista está completa: se lee de la estructura que produce ese JSON, así que no puede ser más corta que lo que se envía. Los campos marcados como opcionales faltan cuando no tienen nada que decir.
Lo que no está no es un olvido. No está el texto del error, no está el cuerpo de la respuesta, no está la URL del destino — porque pueden citar una dirección que contiene los secretos del espacio de trabajo ya resueltos — no está ninguna dirección de correo y no está el identificador de una persona. Un canal compartido queda fuera de nuestro perímetro, y un POST no puede llevar lo que la estructura no tiene.
The body shape the target expects. It decides only the shape, never the destination: webhook sends the payload as JSON to any compatible endpoint.
| Nombre | Tipo | Notas |
|---|---|---|
event | string | always present |
job_id | string | optional |
job_name | string | optional |
environment | string | optional |
failures | integer | optional |
last_attempt_at | string (date-time) | optional |
failure_kind | string | optional |
http_status | integer | optional |
Firma y verificación
No hay firma, y no hay ninguna cabecera que verificar. La dirección es la credencial: los tokens de Slack y de Discord viven en su ruta, y por eso solo se acepta https, la dirección se cifra en reposo y ninguna ruta te la vuelve a leer.
Aquello con lo que sí puedes contar es poco y conviene saberlo. La llamada llega por TLS y se presenta como Postqron-Alerts/1. Nunca se sigue una redirección: un 3xx es una respuesta final, y fallida, así que nada puede desviar el cuerpo a otro sitio después de salir.
Si necesitas la certeza de que una llamada es nuestra, pon un secreto tuyo en la ruta de la dirección que registras y compruébalo al llegar. Es la misma propiedad que te habría dado la firma, y ya funciona hoy.
Una entrega que no sale no es un silencio: es una fila con su motivo y con el estado de la última respuesta, legible en el panel junto al canal. Tras suficientes fallos consecutivos el canal se suspende, con la razón adjunta.