Webhook di avviso
Un secondo canale per l’avviso che un cronjob è fallito, accanto all’email e mai al suo posto.
Versione del contratto 1.15.0 Il riferimento qui sotto è letto dal contratto OpenAPI, che è scritto in inglese. Non è tradotto di proposito: tradurlo vorrebbe dire ricopiarlo, e una copia prima o poi diverge. Scarica il contratto pubblico (OpenAPI, JSON)
Che cos’è un webhook qui
Registri un indirizzo https; quando un cronjob è fallito in modo definitivo, gli mandiamo un POST. Slack e Discord leggono un campo solo e ricevono una riga di testo; qualunque altro bersaglio riceve il JSON descritto più sotto.
Il canale è tuo e non del workspace. Due persone della stessa squadra hanno due destinazioni diverse, e nessun ruolo — nemmeno Admin — può leggere quella di un altro membro. Un cronjob che fallisce deve svegliare chi è di turno.
È un canale in più, mai un canale al posto di: l’email resta accesa per impostazione predefinita, perché altrimenti un webhook che smette di funzionare spegnerebbe gli avvisi senza dirlo.
Registrare e ispezionare un canale
Un canale si registra, si elenca e si rimuove dalla dashboard, e quelle rotte non stanno in questa pagina perché nessuna chiave le raggiunge. Vogliono una sessione e non una chiave API, e l’asimmetria è deliberata: una chiave capace di sostituire l’indirizzo di un webhook potrebbe dirottare gli avvisi del workspace su una destinazione sua — scoprendo quali cronjob falliscono, e quando — mentre chi lo possiede continua a vedere un canale che sembra configurato.
Nessuna rotta restituisce mai un indirizzo, nemmeno i suoi ultimi caratteri. A identificare un canale in un elenco sono il nome che hai scelto e l’host.
Gli eventi che escono
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.
| Nome | Tipo | Note |
|---|---|---|
job_failed |
Che cosa porta il corpo
L’elenco è completo: è letto dalla struttura che produce quel JSON, quindi non può essere più corto di ciò che parte. I campi marcati come facoltativi mancano quando non hanno niente da dire.
Ciò che non c’è non è una dimenticanza. Non c’è il testo dell’errore, non c’è il corpo della risposta, non c’è l’URL del bersaglio — perché possono citare un indirizzo che contiene i segreti del workspace già risolti — non c’è un indirizzo email e non c’è l’identificativo di una persona. Un canale condiviso sta fuori dal nostro perimetro, e un POST non può portare ciò che la struttura non ha.
The body shape the target expects. It decides only the shape, never the destination: webhook sends the payload as JSON to any compatible endpoint.
| Nome | Tipo | Note |
|---|---|---|
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 e verifica
Non c’è una firma, e non c’è un’intestazione da verificare. L’indirizzo è la credenziale: i token di Slack e di Discord stanno nel suo percorso, ed è per questo che si accetta solo https, che l’indirizzo è cifrato a riposo e che nessuna rotta te lo rilegge.
Ciò su cui puoi contare al suo posto è poco e vale la pena saperlo. La chiamata arriva su TLS e si presenta come Postqron-Alerts/1. Nessun redirect viene mai seguito: un 3xx è una risposta finale, e non riuscita, quindi nulla può dirottare altrove il corpo dopo la partenza.
Se ti serve la certezza che una chiamata sia nostra, metti un segreto tuo nel percorso dell’indirizzo che registri e verificalo all’arrivo. È la stessa proprietà che ti avrebbe dato la firma, e funziona già oggi.
Una consegna che non riesce non è un silenzio: è una riga con il suo motivo e con lo stato dell’ultima risposta, leggibile nella dashboard accanto al canale. Dopo abbastanza fallimenti consecutivi il canale viene sospeso, con la ragione allegata.