(Consegna dei webhook · Nautilus)
Il tuo prodotto pubblica un evento con una chiamata API. Nautilus lo mette in coda, lo firma e lo consegna a ogni endpoint iscritto a quel tipo di evento. Una consegna fallita viene ritentata con un programma fisso, e ogni tentativo compare nella tua dashboard con la risposta ottenuta.
curl -X POST https://api.vernesoft.com/v1/relay/messages \
-H "Authorization: Bearer vrn_relay_•••" \
-d '{"event_type":"user.created","payload":{"id":"usr_123"}}'(Costruire o comprare)
La prima versione è una richiesta POST in un ciclo di nuovi tentativi. Smette di essere semplice quando il server di un cliente resta giù per un fine settimana, quando il deploy di un handler esce rotto e un'ora di eventi va rinviata, e quando un endpoint lento comincia a trattenere tutti gli altri.
Costruirlo da te
Consegna dei webhook in Nautilus
(Funzionalità principali)
(01)
Una risposta diversa da 2xx, o un timeout, conta come tentativo fallito. Il messaggio viene ritentato a intervalli crescenti: 8 tentativi in circa 28 ore, lo stesso programma per ogni endpoint. La consegna è at-least-once, quindi un nuovo tentativo può raggiungere il server del tuo cliente più di una volta.
(02)
Ogni messaggio è firmato con HMAC SHA-256, con un segreto che appartiene a un endpoint. Ogni consegna porta tre header (svix-id, svix-timestamp e svix-signature), e la firma copre id, timestamp e body, così i tuoi clienti possono verificare chi l'ha inviato e rifiutare una richiesta ripetuta.
(03)
Pubblicare un evento restituisce 202 appena il messaggio è in coda. La consegna ai server dei tuoi clienti avviene dopo, quindi un endpoint lento o morto non rallenta la richiesta che il tuo codice sta aspettando.
(04)
Pubblica un evento, per esempio user.created, e viene consegnato a ogni endpoint iscritto a quel tipo di evento. Aggiungi un canale a un messaggio per raggiungere solo gli endpoint in ascolto su di esso.
(05)
Ogni tentativo è registrato con l'ora, il codice di risposta e il body della risposta restituita dal tuo server, così vedi perché una consegna è fallita. Nella scheda Events della tua dashboard puoi reinviare una consegna, o rieseguire tutto ciò che è fallito da un momento a tua scelta, fino a 14 giorni indietro.
(06)
Invia una idempotency_key e una chiamata ripetuta restituisce il messaggio originale invece di crearne un secondo. La consegna in sé è at-least-once: un retry può raggiungere di nuovo i tuoi clienti, quindi devono deduplicare sull'header svix-id, che resta uguale a ogni tentativo per lo stesso messaggio.
(Parte di Nautilus)
La consegna dei webhook è una parte di Nautilus, non un servizio a sé. Condivide account e dashboard con l'accesso e i job cron. Gli eventi di accesso, come una nuova registrazione, raggiungono il tuo backend allo stesso modo, come webhook firmati e ritentati.
(Esperienza sviluppatore)
Pubblica un evento con una sola chiamata: tramite un SDK ufficiale per Node, Python, PHP o Rust, oppure con una semplice richiesta HTTP se preferisci non aggiungere dipendenze.
curl -X POST https://api.vernesoft.com/v1/relay/messages \
-H "Authorization: Bearer $VERNE_RELAY_KEY" \
-H "Content-Type: application/json" \
-d '{
"event_type": "subscription.renewed",
"payload": { "user_id": "usr_987", "plan": "pro_tier" },
"idempotency_key": "evt_5f3c9a"
}'(FAQ)
Nautilus genera un segreto unico per ogni endpoint e firma ogni richiesta in uscita con HMAC SHA-256. Ogni consegna porta tre header: svix-id, svix-timestamp e svix-signature. La firma è calcolata su svix-id, svix-timestamp e il body grezzo, uniti da punti, così chi riceve può verificare l'autenticità e rifiutare una ripetizione. Le librerie Svix ufficiali controllano tutto con una chiamata.
Qualsiasi risposta diversa da 2xx, e qualsiasi timeout, conta come tentativo fallito. Il messaggio viene ritentato con un programma fisso a intervalli crescenti: 8 tentativi in circa 28 ore, il che evita di sovraccaricare server che si stanno ancora riprendendo. Il programma è lo stesso per tutti gli endpoint e non si può cambiare. Un endpoint che fallisce ogni tentativo per cinque giorni viene disattivato, e nulla ti avvisa, quindi dai un'occhiata ogni tanto alla scheda Events. Quando il tuo server è tornato, puoi reinviare le consegne fallite dalla dashboard, o rieseguire tutto ciò che è fallito da un momento a tua scelta.
Sì. Esponi il tuo endpoint locale con un tunnel come ngrok o Cloudflare Tunnel e aggiungi quell'URL come endpoint nella dashboard. Usa una chiave live: gli eventi inviati con una chiave di test vengono accettati ma non consegnati. Il registro delle consegne ti permette di ispezionare ogni tentativo mentre provi.
Puoi, ed è molto più di un POST: una coda e backoff esponenziale, segreti per endpoint e firma HMAC, un modo per deduplicare un invio ritentato e un registro delle consegne che il tuo supporto può consultare quando un cliente dice che l'evento non è mai arrivato. Nautilus ha questa lista già pronta, e paghi a richiesta API. Ciò a cui rinunci è il controllo: il programma dei tentativi è fisso, gli endpoint si aggiungono dalla dashboard e non dall'API, e il motore sotto è Svix, che è open source se mai dovessi farlo girare tu.
Oggi non tramite l'API. Gli endpoint si creano nella dashboard, quindi se vuoi che i tuoi clienti incollino il proprio URL nelle impostazioni del tuo prodotto, quella schermata tocca a te costruirla, e per ora qualcuno con accesso alla dashboard aggiunge l'URL. Pubblicare eventi e rileggerli è disponibile tramite l'API.
(Inizia)
La consegna dei webhook è una parte di Nautilus: lo stesso account e la stessa dashboard di accesso e job cron.
Quanto costa costruirlo
Costruirlo non è la parte cara. Una coda, un retry con backoff e un helper per la firma sono una settimana di lavoro, e la maggior parte dei team ci arriva senza fatica. La spesa comincia la settimana dopo, quando un cliente dice che un evento non è mai arrivato e rispondere significa leggere i log a mano. E non finisce, perché ogni nuovo endpoint cliente è un nuovo modo in cui la consegna può fallire.
In più consuma la tua attenzione dove non rende nulla. Nessuno ha scelto il tuo prodotto perché i tuoi retry usano il backoff esponenziale. Ma un webhook che ha smesso di arrivare in silenzio è prima un ticket di supporto, poi una conversazione su un rimborso e a volte un cliente che se ne va. Conseguenze alte, nessun merito: esattamente la forma di una cosa da comprare invece che da costruire.
Se preferisci costruirlo, costruiscilo: il progetto non è un segreto e faremmo quasi le stesse scelte. Calcolane solo il costo come di un servizio che gestirai per anni, non come uno sprint. Se preferisci di no, un endpoint che hai già può ricevere consegne firmate e ritentate non appena hai una chiave API e il suo URL è nella dashboard, e le prime 3.000 richieste di ogni mese sono gratis.