Webhooks d’alerte
Un second canal pour l’alerte qu’une tâche cron a échoué, à côté du courriel et jamais à sa place.
Version du contrat 1.15.0 La référence ci-dessous est lue dans le contrat OpenAPI, rédigé en anglais. Elle n’est pas traduite à dessein: la traduire reviendrait à la recopier, et une copie finit par diverger. Télécharger le contrat public (OpenAPI, JSON)
Ce qu’est ici un webhook
Vous déclarez une adresse https; quand une tâche cron a échoué définitivement, nous lui envoyons un POST. Slack et Discord ne lisent qu’un champ et reçoivent une ligne de texte; toute autre cible reçoit le JSON décrit plus bas.
Le canal est le vôtre et non celui de l’espace de travail. Deux personnes de la même équipe ont deux destinations différentes, et aucun rôle — pas même Admin — ne peut lire celle d’un autre membre. Une tâche cron qui échoue doit réveiller la personne d’astreinte.
C’est un canal en plus, jamais un canal à la place de: le courriel reste actif par défaut, sans quoi un webhook qui cesse de fonctionner éteindrait les alertes sans le dire.
Déclarer et consulter un canal
Un canal se déclare, se consulte et se retire depuis le tableau de bord, et ces routes ne figurent pas sur cette page parce qu’aucune clé ne les atteint. Elles veulent une session et non une clé API, et l’asymétrie est délibérée: une clé capable de remplacer l’adresse d’un webhook pourrait détourner les alertes de l’espace de travail vers une destination à elle — apprenant quelles tâches cron échouent, et quand — pendant que la personne qui le possède continue de voir un canal qui a l’air configuré.
Aucune route ne rend jamais une adresse, pas même ses derniers caractères. Ce qui identifie un canal dans une liste, c’est le nom choisi et l’hôte.
Les événements qui sortent
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.
| Nom | Type | Remarques |
|---|---|---|
job_failed |
Ce que porte le corps
La liste est complète: elle est lue dans la structure qui produit ce JSON, elle ne peut donc pas être plus courte que ce qui part. Les champs marqués facultatifs manquent lorsqu’ils n’ont rien à dire.
Ce qui n’y est pas n’est pas un oubli. Pas de texte d’erreur, pas de corps de réponse, pas d’URL de cible — car elles peuvent citer une adresse contenant les secrets de l’espace de travail déjà résolus — pas d’adresse de courriel et pas d’identifiant de personne. Un canal partagé est hors de notre périmètre, et un POST ne peut pas porter ce que la structure n’a pas.
The body shape the target expects. It decides only the shape, never the destination: webhook sends the payload as JSON to any compatible endpoint.
| Nom | Type | Remarques |
|---|---|---|
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 |
Signature et vérification
Il n’y a pas de signature, ni d’en-tête à vérifier. L’adresse est l’identifiant secret: les jetons de Slack et de Discord vivent dans son chemin, et c’est pourquoi seul https est accepté, pourquoi l’adresse est chiffrée au repos, et pourquoi aucune route ne vous la relit.
Ce sur quoi vous pouvez compter à la place est étroit et mérite d’être su. L’appel arrive en TLS et se présente comme Postqron-Alerts/1. Aucune redirection n’est jamais suivie: un 3xx vaut réponse finale, et manquée, donc rien ne peut détourner le corps ailleurs une fois parti.
S’il vous faut la certitude qu’un appel vient de nous, mettez un secret à vous dans le chemin de l’adresse que vous déclarez et vérifiez-le à l’arrivée. C’est la propriété même qu’une signature aurait apportée, et elle existe déjà.
Une livraison qui ne part pas n’est pas un silence: c’est une ligne avec son motif et le statut de la dernière réponse, lisible dans le tableau de bord à côté du canal. Après assez d’échecs consécutifs, le canal est suspendu, motif à l’appui.