WhatsApp-webhooks: berichten rechtstreeks naar je server routeren

Wat verstuurt Meta precies naar een webhook?

Gebeurtenissen, ingedeeld in categorieën. Het onderscheid bepaalt je architectuur.

Het berichtpad bevat wat klanten versturen en bij een Coexistence-nummer ook echo's van wat je team vanuit de WhatsApp Business-app verstuurt. Dat zijn de velden messages en smb_message_echoes, waarin de gespreksinhoud staat.

Het operationele pad bevat al het andere: account_update wanneer de verbindingsstatus verandert, phone_number_quality_update wanneer kwaliteit of verwerkingssnelheid wijzigt, account_alerts, account_review_update, business_capability_update en phone_number_name_update. Deze bevatten geen gespreksinhoud en vormen de basis voor monitoring.

Een provider die zichzelf in het berichtpad plaatst, ontvangt de eerste groep. Een provider die dat niet doet, ontvangt die niet.

Hoe verifieert Meta een endpoint?

Met een GET-verzoek voordat Meta iets aflevert. Het mislukken hiervan is de meest voorkomende reden waarom een installatie die klaar lijkt geen bericht ontvangt.

Meta roept je URL aan met hub.mode ingesteld op subscribe, je hub.verify_token en een waarde voor hub.challenge. Je endpoint moet die challenge als onbewerkte antwoordtekst teruggeven, niet verpakt in JSON en zonder toevoegingen. Als dat niet gebeurt, begint Meta nooit met afleveren en meldt geen enkel dashboard dit.

Het endpoint moet ook HTTPS gebruiken. Een endpoint dat stil een 404 teruggeeft, of achter een authenticatielaag staat die Meta afwijst, lijkt tot aan het uitblijven van het eerste bericht identiek aan een werkende installatie.

Kan de bestemming naar je eigen server wijzen?

Ja, en hierin verschillen providers van elkaar.

Meta laat een app bepalen waar een bepaald WhatsApp Business Account zijn webhooks aflevert. Wij stellen die override in op jouw URL, waardoor de gebeurtenissen uit het berichtpad van onze callback naar jou gaan. De operationele gebeurtenissen houden we wel, omdat het dashboard en de waarschuwingen daarop zijn gebaseerd.

Het gevolg is architectonisch en geen beleid dat we publiceren. Gespreksinhoud kan aan onze kant nergens worden opgeslagen, omdat die nooit bij ons wordt afgeleverd. Een account zonder ingestelde override valt terug op onze standaard-callback, waar de verwerker deze gebeurtenissen weggooit zonder ze op te slaan.

Wat gebeurt er met de bestemming wanneer een nummer opnieuw verbinding maakt?

Die wordt verwijderd. Bijna niemand houdt rekening met dit probleem.

De bestemming is geen eigenschap van het telefoonnummer. Het is een override op het app-abonnement van onze app op het WhatsApp Business Account. Wanneer een verbinding wordt verwijderd, door Meta's regel voor veertien dagen inactiviteit of anderszins, wordt de app van dat account verwijderd en verdwijnt de override mee.

Opnieuw verbinden herstelt het versturen en de monitoring. Het herstelt niet de aflevering naar je server en er wordt geen fout gemeld. Het eerste signaal is daarom vaak een klant die zegt dat niemand heeft geantwoord. We passen de override na elke nieuwe verbinding opnieuw toe, omdat dit gebeurde met een echt nummer dat probleemloos opnieuw verbinding maakte en daarna stilviel.

Veelgemaakte fouten

• JSON teruggeven vanuit de verificatie-GET. Meta wil de onbewerkte waarde van hub.challenge en niets anders.
• Een tijdelijke of test-URL gebruiken. Meta blijft daar afleveren nadat de tool die de URL genereerde niet meer luistert.
• Aannemen dat de bestemming een nieuwe verbinding overleeft. Die staat op een app-abonnement en wordt ermee verwijderd.
• Het endpoint achter authenticatie plaatsen die Meta's verzoek afwijst.

Veelgestelde vragen

Lees verder