Webhook vs API: Quando Chiedere i Dati e Quando Riceverli

Webhook vs API

Webhook vs API: Push vs Pull, Firme, Retry | We.Inc

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

  • Richiesta API (pull)
  • Webhook (push)
  • Chi la avvia
  • Il tuo codice
  • L'altro servizio
  • Tempistica
  • Quando chiedi, o con un timer di polling
  • Subito dopo l'evento
  • Ti serve
  • Una API key e un client
  • Un endpoint HTTPS pubblico
  • Verifica del mittente
  • Il provider controlla la tua chiave
  • Tu controlli la firma del provider
  • Quando qualcosa fallisce
  • Vedi l'errore e riprovi
  • Il provider riprova; tu devi gestire i duplicati
  • Ideale per
  • Leggere o modificare dati su richiesta
  • Reagire a eventi che non hai causato tu

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.

  • Registra presso il provider un URL sul tuo server e scegli gli eventi che ti interessano.
  • Il provider firma il corpo di ogni evento con un segreto condiviso e lo invia con una POST a quell'URL.
  • Il tuo endpoint ricalcola la firma sul corpo grezzo, rifiuta quelle che non corrispondono e risponde 2xx velocemente.
  • Un job in background svolge il lavoro vero, saltando qualsiasi id evento già elaborato.
  • Verifica sui byte grezzi del corpo. Fare il parsing e riserializzare il JSON cambia gli spazi e rompe la firma.
  • Confronta le firme con una funzione a tempo costante come crypto.timingSafeEqual, mai con ===.
  • Salva gli id degli eventi elaborati con un vincolo di unicità, così un retry o un duplicato diventa un'operazione innocua che non fa nulla.
  • Non dare per scontato che gli eventi arrivino in ordine. Recupera l'oggetto aggiornato dall'API quando l'ordine conta.
  • Tieni un job di riconciliazione lento che interroga l'API una volta al giorno, per recuperare gli eventi mai arrivati.

Domande frequenti

Un webhook è un tipo di API?

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.

Meglio il polling o i webhook?

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.

Come so che un webhook arriva davvero dal provider?

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.

Cosa succede se il mio endpoint non è raggiungibile?

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.

Perché un gestore di webhook dovrebbe rispondere prima di fare il lavoro?

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.

Pull: chiamare un'API

  • Una richiesta API è una domanda che pone il tuo codice: dammi l'ordine 42, elenca le iscrizioni di oggi, crea questo cliente. Scegli tu quando chiedere e ricevi subito una risposta, compreso un errore chiaro se qualcosa è andato storto.
  • Il prezzo è che vieni a sapere delle modifiche solo quando chiedi. Per accorgerti dei nuovi eventi devi fare polling a intervalli, e la maggior parte delle interrogazioni torna vuota.

Push: ricevere un webhook

  • Un webhook è il provider che chiama te. Quando l'evento accade, invia con una POST una descrizione JSON all'URL che hai registrato, di solito entro pochi secondi.
  • Poiché chiunque su internet può inviare una POST a quell'URL, il corpo non è affidabile finché la sua firma non viene verificata. Poiché le reti falliscono, lo stesso evento può arrivare più di una volta o fuori ordine. Un buon ricevitore è costruito per entrambe le cose fin dal primo giorno.

Usarli insieme

  • Uno schema comune e robusto tratta il webhook come un campanello. Ti dice quale oggetto è cambiato; poi chiami l'API per leggere lo stato attuale di quell'oggetto e agire di conseguenza. Così eviti i problemi di ordinamento e i payload obsoleti, e un polling giornaliero recupera tutto ciò che il campanello si è perso.

Un ricevitore di webhook che verifica la firma

Node ed Express: HMAC SHA-256 sul corpo grezzo

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.

Gestire retry e duplicati

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.

Registrare ogni id evento una sola volta (PostgreSQL)

ON CONFLICT DO NOTHING non restituisce alcuna riga per un duplicato, e il tuo codice lo tratta come già gestito.

L'alternativa del polling

Il polling è più semplice da ospitare ma più lento e verboso. Tieni un cursore così ogni interrogazione chiede solo ciò che è nuovo.

Verificatore di firme HMAC SHA-256

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

Correlati: Guide

Prodotto

Per chi è

Funzionalità

Risorse

Azienda

Mappa del sito