how-to · risposta con fonti
Come funzionano i webhook di Resend?
I webhook di Resend inviano una richiesta HTTPS POST con un payload JSON dell'evento al tuo endpoint registrato quando si verifica un evento relativo a un'email, un contatto, un dominio o una soppressione. Il tuo endpoint deve verificare la firma sul corpo grezzo della richiesta, elaborare l'evento in modo idempotente e restituire rapidamente una risposta di successo.
Il flusso dei webhook di Resend
Il flusso inizia quando crei un endpoint HTTPS pubblico e lo registri in Resend con i tipi di evento di cui la tua applicazione ha bisogno. Quando si verifica un evento corrispondente, Resend invia una richiesta POST con un payload JSON. Il payload include un tipo come email.sent, email.delivered, email.bounced o email.complained, un orario di creazione e dati specifici dell'evento. Instrada l'elaborazione in base al campo type, invece di presumere che ogni payload abbia la stessa struttura.
Verifica la richiesta prima di elaborarla
Leggi la richiesta come testo grezzo e verificala con il secret di firma del webhook e con le intestazioni svix-id, svix-timestamp e svix-signature. Fallo prima di analizzare il payload o di agire in base a esso. Analizzare il JSON e poi serializzarlo di nuovo può cambiare i byte e far fallire una firma legittima. Rifiuta le richieste che non superano la verifica e conserva il secret di firma in un secret manager o in una variabile d'ambiente protetta, non nel codice sorgente.
Rendi idempotente la gestione degli eventi
Resend dichiara una consegna at-least-once, quindi lo stesso evento può raggiungere il tuo endpoint più di una volta. Memorizza lo svix-id con un vincolo di unicità e salta la logica di business quando quell'identificatore è già stato elaborato. Non fare affidamento nemmeno sull'ordine di arrivo, perché i nuovi tentativi e i ritardi di rete possono riordinare gli eventi. Usa il valore created_at dell'evento quando la sequenza conta, e modella i cambi di stato in modo che un evento più vecchio non possa sovrascrivere per errore uno stato più recente.
Conferma subito ed elabora in sicurezza
Restituisci HTTP 200 dopo che l'evento è stato verificato e registrato in modo persistente, poi esegui le operazioni più lente tramite una coda o un worker in background. Un timeout o una risposta diversa da un successo provoca un nuovo tentativo di consegna, quindi gli handler sincroni lunghi generano duplicati evitabili. Separa l'acquisizione dagli effetti collaterali, come l'aggiornamento di un record di soppressione, la notifica al supporto o la registrazione di un bounce. Anche ogni effetto collaterale deve poter essere ripetuto senza danni o essere protetto dall'identificatore dell'evento memorizzato.
Testa nuovi tentativi, replay e ripristino dagli errori
Prima di andare in produzione, testa l'endpoint con tipi di evento rappresentativi, comprese firme non valide, identificatori duplicati, timestamp fuori ordine ed errori temporanei del database. Resend ritenta le consegne fallite secondo un calendario di backoff e ti consente il replay sia dei messaggi webhook falliti sia di quelli riusciti. Usa il replay per ripristinare il servizio dopo un'interruzione o per convalidare il codice aggiornato dell'handler, ma mantieni attiva la deduplicazione, così il ripristino non ripete effetti collaterali visibili ai clienti.
Le domande dei team
Quale risposta deve restituire un endpoint webhook di Resend?
Restituisci HTTP 200 dopo che la richiesta è stata verificata e l'evento accettato in modo persistente. Le operazioni lente devono proseguire in modo asincrono, così il provider non ritenta a causa di un timeout.
Perché bisogna conservare il corpo grezzo della richiesta?
La firma copre i byte originali della richiesta. Analizzare e serializzare di nuovo il JSON può alterare quei byte e far fallire la verifica anche quando la richiesta è legittima.
Un evento webhook di Resend può essere consegnato più di una volta?
Sì. Resend dichiara una consegna at-least-once, quindi gli handler devono deduplicare gli eventi, di solito memorizzando lo svix-id univoco prima di applicare gli effetti collaterali di business.
Gli eventi webhook di Resend vengono consegnati in ordine?
No. Ritardi di rete e nuovi tentativi possono cambiare l'ordine di arrivo. Usa i timestamp degli eventi e regole di transizione di stato quando la tua applicazione deve ricostruire una sequenza affidabile.
Come si recuperano le consegne fallite dei webhook di Resend?
Resend ritenta automaticamente le consegne fallite e supporta anche il replay manuale. Correggi prima l'endpoint, poi esegui il replay degli eventi necessari mantenendo attivi i controlli di idempotenza.
Fonti primarie
- Gestione dei webhook — Resend
- Verificare le richieste dei webhook — Resend
- Nuovi tentativi e replay — Resend
- Tipi di evento dei webhook — Resend