Webhook vs API spiegati con una tabella di confronto, i compromessi tra polling e push, un verificatore di firme HMAC nel browser, la gestione dei retry e codice di ricezione idempotente.
Con una chiamata API, il tuo codice chiede dati a un altro servizio quando vuole: questo è il pull. Con un webhook, il servizio invia una HTTP POST al tuo URL nel momento in cui succede qualcosa: questo è il push. La maggior parte delle integrazioni usa entrambi, un webhook per sapere subito di una modifica e una chiamata API per recuperare il record completo e aggiornato.
Richiesta API vs webhook
Interrogare un'API ogni minuto per sapere se un pagamento è andato a buon fine spreca richieste e arriva comunque in ritardo. Un webhook inverte la direzione, ma sposta anche la responsabilità su di te: il tuo endpoint deve essere pubblico, dimostrare che ogni messaggio è autentico, rispondere in fretta e gestire lo stesso evento che arriva due volte. Questa pagina copre ognuno di questi compiti con codice da copiare.
In senso lato, sì. È una richiesta HTTP con un corpo JSON, solo inviata nella direzione opposta. A volte lo si chiama API inversa. La differenza che conta è chi avvia la conversazione e chi deve essere online per riceverla.
Usa i webhook quando il provider li offre per gli eventi che ti servono e puoi ospitare un endpoint HTTPS pubblico. Usa il polling quando non esiste un webhook, quando sei dietro un firewall, o per pochi controlli in cui un minuto di ritardo va bene.
La maggior parte dei provider invia in un header un HMAC SHA-256 del corpo, calcolato con un segreto che conoscete solo tu e loro. GitHub, per esempio, usa X-Hub-Signature-256 con il prefisso sha256=; Stripe usa Stripe-Signature con un timestamp. Ricalcolalo e confrontalo prima di fidarti di qualsiasi cosa.
La maggior parte dei provider riprova le consegne fallite con intervalli crescenti tra un tentativo e l'altro, per un periodo che dipende dal provider. Stripe, per esempio, continua a riprovare gli eventi live fino a tre giorni. Dopo, l'evento è disponibile solo tramite la sua API o la dashboard.
I provider aspettano una risposta solo per poco tempo. Se il tuo codice prima invia email o chiama altri servizi, la consegna può andare in timeout ed essere ritentata, anche se hai già agito. Metti il job in coda, restituisci 200 ed elabora dopo.
express.raw mantiene il corpo come byte così la firma corrisponde. Questo formato di header segue la convenzione sha256= di GitHub; adatta il nome dell'header per altri provider.
Un indice unico sull'id dell'evento fa fallire l'inserimento alla seconda consegna, così il lavoro viene eseguito una sola volta indipendentemente da quante volte arriva l'evento.
ON CONFLICT DO NOTHING non restituisce alcuna riga per un duplicato, e il tuo codice lo tratta come già gestito.
Il polling è più semplice da ospitare ma più lento e verboso. Tieni un cursore così ogni interrogazione chiede solo ciò che è nuovo.
Incolla un corpo e un segreto per calcolare la firma che invierebbe un provider, poi incolla l'header ricevuto per confrontarli. Tutto gira nel tuo browser con la Web Crypto API; non viene inviato nulla.
Corpo grezzo della richiesta
Segreto del webhook
Firma che questo corpo dovrebbe avere
Header della firma ricevuto (facoltativo)
Corrisponde: il corpo e il segreto producono questa firma.
Non corrisponde: il corpo è cambiato, il segreto è sbagliato oppure l'header usa un altro formato.
Calcolo in corso
Inizia gratis · Nessuna carta di credito richiesta