Notifiche webhook: payload, header e nuovi tentativi

Oltre all'email e alla campanella delle notifiche nell'app, Pingsured può inviare un avviso come richiesta HTTP a un URL che scegli tu: il tuo strumento di gestione degli incidenti, un'integrazione chat, una piattaforma di automazione o un tuo endpoint. I webhook sono disponibili dal piano Team in su e vengono configurati da un proprietario o da un gestore dell'account, per un singolo ping o come impostazione predefinita per tutti i ping dell'account.

La richiesta

Ogni avviso è una richiesta POST con un corpo JSON:

l'URL deve usare https;
Content-Type: application/json;
User-Agent: Pingsured-Alarm/1;
vengono seguiti fino a 3 reindirizzamenti;
il tuo endpoint ha 10 secondi per rispondere con un codice di stato 2xx.

Gli indirizzi in reti private, di loopback o link-local vengono rifiutati, anche quando un nome pubblico si risolve in uno di questi indirizzi o un reindirizzamento vi rimanda.

Il payload

Campo	Significato
`event`	`alarm.fired`, oppure `alarm.fired.test` per il pulsante «Invia test»
`version`	la versione del payload, attualmente `1`
`account_id`	l'account a cui appartiene il ping
`task_id`	l'ID del ping
`task_name`	il nome del ping come appare nell'app
`channel`	sempre `webhook`
`trigger`	la regola che è scattata, come `first_error` o `first_ok`
`result.status`	lo stato attuale del ping: `ok`, `warning`, `error` o `unknown`
`result.prev_status`	lo stato prima di questo cambiamento, se ce n'era uno
`result.started_at`	quando è stato eseguito il controllo che ha prodotto questo risultato, in ISO 8601 UTC
`result.location`	la località i cui controlli hanno fatto scattare l'avviso, ad esempio `de` o `us-west`

Un avviso tipico quando un sito smette di rispondere:

event: alarm.fired
trigger: first_error
result.status: error, result.prev_status: ok

e quando torna a funzionare, lo stesso con trigger first_ok e gli stati invertiti.

Header per instradamento e deduplicazione

X-Pingsured-Event ripete il nome dell'evento, così puoi instradare la richiesta senza analizzare il corpo.
X-Pingsured-Event-Version ripete la versione del payload.
X-Pingsured-Delivery identifica la consegna. Il valore resta lo stesso quando la consegna viene ritentata: salvalo e ignora una seconda richiesta con un ID che hai già elaborato.

Nuovi tentativi

Quando il tuo endpoint non risponde in tempo, non è raggiungibile oppure risponde con 408, 425, 429 o con un qualsiasi codice 5xx, la consegna viene ritentata: cinque tentativi in tutto, a distanza di 30 secondi, 5 minuti, 30 minuti e 2 ore. Qualsiasi altra risposta 4xx è considerata definitiva e non viene ritentata, e lo stesso vale per un URL rifiutato prima dell'invio (http semplice, un indirizzo privato, troppi reindirizzamenti).

Quando vengono inviati i webhook

Un webhook segue le stesse regole di tutti gli altri canali di avviso:

Quali cambiamenti. La configurazione consigliata avvisa al primo errore e al ripristino. Puoi anche ricevere un avviso per ogni risultato in errore.
Quanti errori prima. Una soglia come «3 degli ultimi 5 controlli» evita di allertare qualcuno per una singola risposta lenta. Le soglie di allarme e di ripristino si impostano separatamente.
Con quale frequenza. Gli avvisi ripetuti per lo stesso ping e lo stesso canale vengono trattenuti per 15 minuti; un cambiamento di stato viene sempre inviato subito.
Da dove. Ogni località da cui un ping viene controllato è valutata singolarmente, e un errore in una qualsiasi di esse è un avviso per il ping.

Non ancora disponibile

Le richieste non sono firmate. Finché non lo saranno, usa un URL con un percorso o un token difficile da indovinare e considera X-Pingsured-Delivery un identificativo, non una prova di provenienza.
Un solo URL webhook per ping, più un URL predefinito per tutto l'account.