Cos'è un webhook?

Quando Bird chiama il tuo endpoint, il ricevitore deve preservare l'evento prima di iniziare qualsiasi elaborazione. Un webhook è una richiesta HTTP che un sistema invia alla tua applicazione quando succede qualcosa. Il mittente firma il POST verso il tuo URL registrato. Il tuo ricevitore decide quando l'evento è accettato in modo durevole.

In cosa si distingue un webhook dal polling di un API?

Polling significa che la tua app chiama un API a intervalli regolari e controlla se ci sono cambiamenti. Un webhook inverte quella direzione: il provider chiama il tuo endpoint quando si verifica un evento, così eviti richieste a vuoto e reagisci prima.

I webhook richiedono un endpoint HTTPS pubblico in grado di ricevere richieste mentre gli eventi vengono consegnati. Il polling funziona da qualsiasi posizione e permette alla tua app di scegliere quando recuperare lo stato. Usa i webhook per le notifiche tempestive. Usa l'API per recuperare maggiori dettagli sulla risorsa quando un evento contiene solo identificatori.

Com'è fatta una richiesta webhook?

Una richiesta webhook è un HTTP POST con header e un envelope evento JSON. L'evento di consegna email di Bird ha type, un timestamp evento e data specifici per tipo:

{
  "type": "email.delivered",
  "timestamp": "2026-06-10T14:30:00Z",
  "data": {
    "email_id": "em_01krdgeqcxet5s7t44vh8rt9mg",
    "recipient_id": "er_01krdgeqcxet5s7t44vh8rt9mg",
    "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
    "recipient": "user@example.com",
    "recipient_role": "to",
    "tags": [{ "name": "category", "value": "welcome" }],
    "metadata": { "order_id": "ord_123" },
    "broadcast_id": null
  }
}

L'ID del messaggio è data.email_id. L'identità della consegna è l'header webhook-id, che resta invariato quando Bird ripete o riproduce quell'evento. Il timestamp nel body registra quando l'evento si è verificato. L'header webhook-timestamp registra questo tentativo di consegna, quindi i due timestamp rispondono a domande diverse. Consulta i campi degli eventi email per i payload specifici per evento.

Come si verifica la firma di un webhook?

Conserva i byte grezzi della richiesta e verifica la firma prima di fare il parsing o salvare l'evento. Bird SDK controlla gli header webhook-id, webhook-timestamp e webhook-signature. Applica automaticamente la tolleranza sul timestamp. Usa la guida alla firma invece di scrivere un secondo verificatore.

Se hai bisogno di capire l'input di firma, Bird usa {webhook-id}.{webhook-timestamp}.{raw request body}. Il secret dell'endpoint inizia con whsec_; rimuovi quel prefisso e decodifica in base64 il resto prima di calcolare HMAC-SHA256. Durante la rotazione del secret, l'header della firma può contenere diversi valori v1, separati da spazi, quindi accetta un valore corrispondente tra i secret attivi.

Rifiuta le richieste malformate, non autenticate o scadute prima di salvarle. Fare il parsing di JSON prima può modificare spazi bianchi o ordine delle chiavi e fa sì che i byte non corrispondano più al messaggio firmato.

Come salvare e confermare un webhook?

Persisti un evento verificato e il relativo lavoro durevole prima di restituire successo. Inserisci l'evento con chiave webhook-id. Inserisci l'elemento di lavoro per un nuovo evento. Esegui il commit di entrambi in un'unica transazione o in un design equivalente con inbox e outbox durevoli.

read raw bytes and headers
verify the signature and timestamp with the Bird SDK
begin a durable transaction
  insert the inbox event keyed by webhook-id, unless it already exists
  insert a durable work item for a new event
commit the transaction
return 204
worker processes the persisted event idempotently

Un duplicato già salvato in modo durevole può ricevere 204 senza creare ulteriore lavoro. Restituisci non-2xx quando il commit durevole fallisce, così Bird ritenta la consegna. Una volta restituito successo, ritenta il worker locale dal tuo record durevole invece di aspettare che Bird invii di nuovo l'evento.

Questo ordine è un design applicativo per la semantica di consegna at-least-once di Bird. Non è una coda che Bird gestisce al posto tuo. La guida a duplicati e idempotenza tratta la decisione sulla deduplicazione in maggior dettaglio.

Come funzionano i retry e il replay dei webhook?

Bird concede a una consegna normale 15 secondi per ricevere una risposta. Qualsiasi stato 2xx è considerato successo. Uno stato non-2xx, un redirect o un timeout è considerato fallimento e segue la pianificazione dei retry.

La curva prevede 8 tentativi inclusa la richiesta iniziale. Ogni ritardo si applica con un jitter di ±20%. Un 429 o un timeout di connessione alza il ritardo base a 60 secondi. Un valore Retry-After positivo viene limitato tra quel ritardo base e il doppio del ritardo base prima del jitter, quindi la tabella descrive ritardi base, non orari di arrivo esatti. Consulta come vengono ritentati i webhook falliti per il percorso di fallimento.

Le consegne non sono ordinate, quindi non aggiornare lo stato corrente dell'applicazione basandoti solo sull'ordine di arrivo. Usa il timestamp dell'evento e lo stato della tua risorsa quando gli eventi possono arrivare fuori ordine.

Quando una consegna viene persa, ispeziona i tentativi webhook. Correggi il ricevitore. Crea un replay webhook. Bird salta le consegne che l'endpoint ha già ricevuto con successo. Un replay riutilizza il webhook-id originale, quindi la stessa chiave di deduplicazione lo protegge.

Cosa collegare dopo aver appreso le basi dei webhook?

Crea un endpoint. Verifica e accetta in modo durevole le sue consegne firmate. Ispeziona i tentativi di consegna. Riproduci gli eventi persi. Poi usa la rotazione del secret per distribuire un nuovo secret di firma senza perdere consegne.