Webhooks: gebeurtenissen van Leat naar je eigen systeem sturen

Met een webhookabonnement roept Leat een URL aan jouw kant aan zodra er een bepaalde gebeurtenis plaatsvindt: een contact wordt aangemaakt of bijgewerkt, er worden punten bijgeschreven, een voucher wordt verzilverd. Leat stuurt een POST-verzoek met de gegevens van die gebeurtenis, ondertekent het en probeert het opnieuw als je endpoint niet antwoordt.

Zo krijg je data uit Leat en in een ander systeem. Gebruik het altijd als de vraag is: "hoe stuur ik X naar mijn systeem als Y gebeurt?"

Webhookabonnement of de Webhook-actie van een automatisering?

Een automatisering heeft ook een Webhook-actie, en die lijkt de snellere route. Het is alleen niet het juiste middel om een ander systeem bij te werken. Vergeleken met een abonnement geldt voor de webhook van een automatisering:

• hij is niet ondertekend, dus je endpoint kan niet controleren of het verzoek van Leat komt
• hij wordt niet opnieuw geprobeerd: ligt je endpoint eruit, dan is die aanroep verloren
• een foutmelding van je endpoint telt toch als verstuurd
• er is geen afleverhistorie, alleen een stapresultaat in de run van de automatisering
• hij gaat alleen af voor contacten die door de filters en de instellingen voor herhaalde deelname van de automatisering komen

Gebruik de Webhook-actie alleen als de aanroep één stap is in een flow die iets nodig heeft wat een abonnement niet kan, zoals een vertraging, een vertakking of een filter. Maak voor al het andere een webhookabonnement aan zoals hieronder beschreven.

Voordat je begint: een privé-app

Webhookabonnementen horen bij een integratie. Voor je eigen systeem is dat een privé-app:

1. Ga naar Apps en dan naar Integraties.
2. Klik op de pagina Marketplace rechtsboven op Maak een privé-app.
3. Geef de app de naam van het systeem dat je koppelt en klik op Aanmaken.

Je komt op de pagina van de privé-app terecht. Later vind je hem in de zijbalk onder Geïnstalleerd.

Op een integratie uit de Marketplace, zoals Shopify of Klaviyo, kun je geen webhooks aanmaken. Die integraties laten de webhooks die ze gebruiken wel zien op hun eigen tabblad Webhooks, maar ze beheren ze zelf.

Een webhook aanmaken

1. Open je privé-app en ga naar het tabblad Webhooks.
2. Klik op Nieuwe webhook.
3. Kies de Gebeurtenis. De Naam wordt ingevuld met de naam van de gebeurtenis, en die kun je aanpassen.
4. Vul de URL van je endpoint in.
5. Klik op Aanmaken.

De webhook is meteen actief en opent op zijn eigen pagina.

Een privé-app kan één webhook per gebeurtenis hebben. Wil je dezelfde gebeurtenis naar twee URL's sturen, maak dan een tweede privé-app aan.

Gebeurtenissen waarop je je kunt abonneren

Contacten:

• contact_created
• contact_updated
• contact_was_subscribed
• contact_was_unsubscribed
• contact_identifier_created
• contact_identifier_updated

Loyaliteit en niveaus:

• credit_reception_created
• points_transaction_created
• tier_reached
• tier_dropped

Beloningen, promoties en vouchers:

• reward_updated
• reward_redeemed
• promotion_updated
• voucher_created
• voucher_updated
• voucher_expired
• voucher_redeemed

Stempelkaarten:

• stamp_card_created
• stamp_card_transaction_created
• stamp_card_redeemed
• stamp_card_redemption_reversed
• stamp_card_expired

De stempelkaartgebeurtenissen bestaan alleen als V2-webhooks. Zie Oudere V1-webhooks hieronder.

Cadeaukaarten en prepaid:

• giftcard_created
• giftcard_updated
• giftcard_transaction_created
• prepaid_transaction_created

Bestellingen, bezoeken en boekingen:

• order_created
• visit_created
• booking_created
• booking_updated

Formulieren en referrals:

• form_submission_completed
• referral_completed

De pagina Webhooks van de API-referentie op docs.leat.com/v3 heeft voor elke gebeurtenis een voorbeeldpayload.

Wat je endpoint ontvangt

Elk verzoek is een POST met een JSON-body. Een webhook die je in het dashboard aanmaakt, stuurt altijd een array met gebeurtenissen, ook als er maar één in zit:

{
  "batch_uuid": "…",
  "version": "V2",
  "event_type": "contact_updated",
  "count": 1,
  "events": [
    {
      "event_uuid": "…",
      "event_type": "contact_updated",
      "data": { "contact": { … } }
    }
  ]
}

De meeste gebeurtenissen gaan los de deur uit, een paar seconden nadat ze plaatsvinden. Leat wacht niet tot een batch vol is. Bulkacties, zoals vouchers uitgeven aan een groep contacten, sturen echte batches van maximaal 100 gebeurtenissen of 1 MB, wat het eerst bereikt is.

Bij de contactgebeurtenissen bevat data.contact het contact zoals het nu is: het e-mailadres, elk aangepast attribuut met zijn waarde, het puntensaldo met de totalen, het niveau en het prepaidsaldo.

contact_updated zegt niet welke attributen er veranderd zijn. Het stuurt het hele contact na de wijziging, dus vergelijk het met wat je zelf hebt opgeslagen als je dat wilt weten.

Controleren of een verzoek van Leat komt

Elk verzoek heeft een Signature-header. Dat is een HMAC-SHA256 van de ruwe request-body, als hexadecimale string in kleine letters, berekend met je geheim.

Bereken dezelfde hash over de body precies zoals je die ontvangen hebt, voordat je hem parset, en vergelijk de twee:

$expected = hash_hmac('sha256', $rawBody, $secret);

if (! hash_equals($expected, $request->header('Signature'))) {
    abort(401);
}

Een nieuwe webhook wordt ondertekend met je accountgeheim, dat je vindt onder Apps → Integraties → Account secret in de zijbalk. Wil je één webhook een eigen geheim geven, open hem dan, klik op Bewerken en vul Geheim in. Laat leeg om het huidige geheim te behouden.

Antwoord met een 2xx, en wat er gebeurt als je dat niet doet

Leat telt een aflevering als geslaagd als je endpoint binnen 20 seconden antwoordt met een 2xx-status. Al het andere, ook een time-out of een geweigerde verbinding, is een mislukking, en dan probeert Leat het opnieuw.

Een aflevering krijgt in totaal 5 pogingen. De wachttijden daartussen zijn ongeveer 1 minuut, 2 minuten, 17 minuten en 3 uur. Na de vijfde mislukking wordt de aflevering gemarkeerd als Mislukt en niet meer opnieuw verstuurd.

De webhook zelf blijft actief en je krijgt geen melding, dus kijk in de geschiedenis als je vermoedt dat er iets ontbreekt.

Bij een nieuwe poging wordt de hele batch opnieuw verstuurd. Sla de event_uuid op van elke gebeurtenis die je verwerkt hebt en sla de gebeurtenissen over die je al gezien hebt.

Zien wat er verstuurd is, en een test versturen

Open de webhook en ga naar het tabblad Geschiedenis. Elke aflevering staat erin met zijn status: In afwachting, Opnieuw proberen, Geslaagd of Mislukt. Je ziet ook het aantal gebeurtenissen erin, het aantal pogingen en de meest recente poging. Klik op een aflevering om de exacte body te zien die gepost is en, per poging, de statuscode die je endpoint teruggaf en hoe lang het duurde.

Afleveringen worden 90 dagen bewaard, de afzonderlijke pogingen 30 dagen.

Wil je je endpoint uitproberen, klik dan op Test op de pagina van de webhook. Die knop is er alleen zolang de webhook actief is. Bij een contactgebeurtenis kies je het contact dat je wilt versturen. Bij elke andere gebeurtenis geldt: De meest recente overeenkomende record in je account wordt gebruikt om de testpayload op te bouwen, dus de test mislukt als je account er nog geen heeft. Een test is een echte aflevering: hij verschijnt in de geschiedenis en wordt opnieuw geprobeerd zoals elke andere.

Een webhook wijzigen, pauzeren of verwijderen

• Bewerken wijzigt de naam, de URL en het geheim. De gebeurtenis kun je niet wijzigen, dus maak voor een andere gebeurtenis een nieuwe webhook aan.
• Deactiveren stopt de afleveringen tot je hem weer activeert. Gebeurtenissen die in de tussentijd plaatsvinden, worden achteraf niet verstuurd.
• Verwijderen is alleen beschikbaar bij een inactieve webhook, dus deactiveer hem eerst.

Als je een privé-app verwijdert, worden al zijn webhooks uitgeschakeld.

Oudere V1-webhooks

Een webhook die is aangemaakt voordat V2 bestond, toont V1 als versie, met een melding dat de ondersteuning voor V1 stopt. Een V1-webhook stuurt één gebeurtenis per verzoek in plaats van een array, en geeft je endpoint 3 seconden om te antwoorden. Gebeurtenissen die na V2 zijn toegevoegd, zoals de stempelkaartgebeurtenissen, hebben geen V1-versie.

De versie van een webhook kun je niet wijzigen. Wil je overstappen, pas dan je endpoint aan zodat het een array met gebeurtenissen accepteert. Deactiveer en verwijder daarna de V1-webhook en maak een nieuwe aan voor dezelfde gebeurtenis, want een privé-app kan maar één webhook per gebeurtenis hebben.

Webhooks beheren via de API

Een ontwikkelaar kan webhookabonnementen ook via de API aanmaken en beheren, op /api/v3/oauth/clients/webhook-subscriptions. Geef bij het aanmaken "version": "V2" mee: zonder die waarde maakt de API een V1-webhook aan. Zie Een eigen integratie bouwen met de Leat API voor tokens en de rest van de API.