Wat is een webhook?

Wanneer Bird je endpoint aanroept, moet de ontvanger het event bewaren voordat de verwerking begint. Een webhook is een HTTP-request dat één systeem naar je applicatie stuurt wanneer er iets gebeurt. De afzender ondertekent het POST naar je geregistreerde URL. Je ontvanger bepaalt wanneer het event duurzaam geaccepteerd is.

Wat is het verschil tussen een webhook en het pollen van een API?

Pollen betekent dat je app een API op een schema aanroept en op wijzigingen controleert. Een webhook keert die richting om: de provider roept je endpoint aan wanneer een event plaatsvindt, zodat je onnodige requests vermijdt en sneller reageert.

Webhooks vereisen een publiek HTTPS-endpoint dat requests kan ontvangen terwijl events worden afgeleverd. Pollen werkt vanaf elke locatie en laat je app kiezen wanneer de status wordt opgehaald. Gebruik webhooks voor tijdige notificaties. Gebruik de API om meer resourcedetails op te halen wanneer een event alleen identifiers bevat.

Hoe ziet een webhook-request eruit?

Een webhook-request is een HTTP POST met headers en een JSON-event-envelope. Het e-mailbezorgingsevent van Bird bevat type, een event-timestamp en typespecifieke data:

{
  "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
  }
}

Het bericht-ID is data.email_id. De bezorgingsidentiteit is de webhook-id-header, die gelijk blijft wanneer Bird dat event opnieuw probeert of opnieuw afspeelt. De timestamp in de body registreert wanneer het event plaatsvond. De webhook-timestamp-header registreert deze bezorgingspoging, dus de twee timestamps beantwoorden verschillende vragen. Zie de e-mail-eventvelden voor eventspecifieke payloads.

Hoe verifieer je een webhook-handtekening?

Bewaar de ruwe requestbytes en verifieer de handtekening voordat je het event parst of opslaat. Bird's SDK controleert de webhook-id-, webhook-timestamp- en webhook-signature-headers. Het past de tijdstempeltolerantie automatisch toe. Gebruik de handtekeninggids in plaats van zelf een tweede verificatie te schrijven.

Als je de ondertekeninginvoer wilt begrijpen: Bird gebruikt {webhook-id}.{webhook-timestamp}.{raw request body}. Het endpoint-secret begint met whsec_; verwijder dat voorvoegsel en base64-decodeer de rest voordat je HMAC-SHA256 berekent. Tijdens secretrotatie kan de handtekeningheader meerdere door spaties gescheiden v1,-waarden bevatten, dus accepteer een overeenkomende waarde uit de actieve secrets.

Weiger misvormde, niet-geauthenticeerde of verlopen requests vóór opslag. Als je JSON eerst parst, kunnen witruimte of sleutelvolgorde veranderen, waardoor de bytes niet meer overeenkomen met het ondertekende bericht.

Hoe sla je een webhook op en bevestig je de ontvangst?

Sla een geverifieerd event en het bijbehorende duurzame werk op voordat je succes retourneert. Voeg het event in met webhook-id als sleutel. Voeg het werkitem in voor een nieuw event. Commit beide in één transactie of een gelijkwaardig duurzaam inbox- en outboxontwerp.

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

Een duplicaat dat al duurzaam is opgeslagen kan 204 ontvangen zonder extra werk te creëren. Retourneer non-2xx wanneer de duurzame commit mislukt, zodat Bird de bezorging opnieuw probeert. Zodra je succes retourneert, hervat je de lokale worker vanuit je duurzame record in plaats van te verwachten dat Bird het event opnieuw stuurt.

Deze volgorde is een applicatieontwerp voor de at-least-once-bezorgingsemantiek van Bird. Het is geen wachtrij die Bird voor je beheert. De gids voor duplicaten en idempotentie behandelt de deduplicatiebeslissing uitgebreider.

Hoe werken webhook-retries en replay?

Bird geeft een normale bezorging 15 seconden om een response te ontvangen. Elke 2xx-status is succesvol. Een non-2xx-status, redirect of timeout mislukt en volgt het retryschema.

De curve bevat 8 pogingen inclusief het initiële request. Elke vertraging krijgt plus of min 20% jitter. Een 429 of verbindingstimeout verhoogt de basisvertraging naar 60 seconden. Een positieve Retry-After-waarde wordt begrensd tussen die basis en tweemaal de basis vóór jitter, dus de tabel beschrijft basisvertragingen in plaats van exacte aankomsttijden. Zie hoe mislukte webhooks opnieuw worden geprobeerd voor het faalpad.

Bezorgingen zijn ongeordend, dus werk de huidige applicatiestatus niet bij op basis van alleen de aankomstvolgorde. Gebruik het event-timestamp en je resourcestatus wanneer events in willekeurige volgorde kunnen aankomen.

Wanneer een bezorging is gemist, bekijk dan de webhookpogingen. Los het probleem met de ontvanger op. Maak een webhook-replay aan. Bird slaat bezorgingen over die het endpoint al succesvol heeft ontvangen. Een replay hergebruikt het originele webhook-id, dus dezelfde dedupesleutel beschermt het.

Wat kun je aansluiten nadat je de webhookbasis hebt geleerd?

Maak een endpoint aan. Verifieer en accepteer duurzaam de ondertekende bezorgingen. Bekijk bezorgingspogingen. Speel gemiste events opnieuw af. Gebruik daarna secretrotatie om een nieuw ondertekeningsecret te deployen zonder bezorgingen te missen.