Consegna e retry

Consegna

Accettiamo solo URL https://, mai indirizzi interni o privati — è la stessa protezione che impedisce a un webhook di diventare una sonda dentro la rete di Aitrack (vedi sotto, “Protezione SSRF”).

• Timeout: 10 secondi.
• Redirect: nessuno seguito (0 redirect ammessi).
• Content-Type: application/json.
• Le consegne allo stesso endpoint sono serializzate: non arrivano in parallelo, per non martellare il tuo server.

Retry

Se il tuo endpoint non risponde 2xx, la consegna viene ritentata secondo la retry_policy scelta in configurazione:

Politica	Comportamento
exponential (default)	gli intervalli raddoppiano — 2, 4, 8, 16 minuti — fino a max_retries tentativi
fixed	ogni 5 minuti, fino a max_retries tentativi
none	nessun retry: un fallimento va subito in dead-letter

max_retries è configurabile 0–10 (default 5). Esauriti i tentativi, la consegna finisce in dead-letter e la puoi rilanciare a mano.

Dead-letter e replay

GET /api/webhooks/dead-letter/list elenca le consegne esaurite (stato exhausted).

Minimizzazione dati (GDPR)

La lista dead-letter non restituisce il payload originale (può contenere posizioni o altri dati personali) e tronca corpo risposta ed errore. Per rielaborare una consegna usa il replay, che rilegge il payload dal database solo in quel momento.

POST /api/webhooks/deliveries/:deliveryId/replay ri-accoda una consegna in stato failed o exhausted per un nuovo tentativo immediato.

Stati di una consegna

pending → delivered (risposta 2xx) oppure failed (in attesa di retry) → exhausted (retry esauriti o retry_policy: none).

Protezione SSRF

L’URL del webhook è scelto da te: senza difese sarebbe un vettore verso servizi interni o metadata cloud. La validazione è applicata due volte:

1. Alla creazione/modifica — rifiuta URL non-https, host loopback, IP letterali privati (400 WEBHOOK_URL_INVALID).
2. Al momento della consegna — ri-validazione con risoluzione DNS, per coprire il DNS rebinding (un hostname può risolvere a un IP privato solo al momento dell’invio, dopo essere stato validato in modo innocuo alla creazione). Se l’URL non è sicuro, la consegna è marcata come fallita senza che parta alcuna richiesta.

Nessun redirect viene seguito, per lo stesso motivo: un endpoint pubblico potrebbe reindirizzare verso un host interno dopo la validazione.

Eventi disponibili

Gli event_type corrispondono ai tipi di trigger delle automazioni configurabili su Aitrack (ingresso/uscita da un’area, sosta, accensione, allarme manomissione, RFID…), più ping per il test manuale dell’endpoint. Un endpoint iscritto a * riceve tutti gli eventi presenti e futuri, senza bisogno di aggiornare la lista a ogni nuovo tipo.

Un endpoint riceve un evento solo se è attivo e la sua lista events contiene quel tipo — oppure il wildcard *.