Een WhatsApp-webhook-endpoint verifiëren
Voordat er een event wordt geleverd, roept Meta je endpoint aan met een GET met hub.mode, hub.verify_token en hub.challenge. Je endpoint moet het token vergelijken en de challenge als ruwe body terugsturen. Al het andere voorkomt dat de levering start.
De waarde die als antwoordbody moet worden teruggestuurd.
De waarde van hub.mode bij een verificatieverzoek.
Het enige schema dat Meta verifieert. HTTP wordt vóór de aanroep afgewezen.
Wat stuurt Meta precies?
Een GET-verzoek naar je URL met drie queryparameters. hub.mode is ingesteld op subscribe. hub.verify_token is het token dat je hebt ingesteld bij het configureren van de bestemming. hub.challenge is een waarde die Meta voor deze poging genereert.
Je endpoint moet hub.verify_token vergelijken met het token dat je hebt gekozen. Als ze overeenkomen, antwoord je met 200 en hub.challenge als de volledige antwoordbody. Niet verpakt in JSON, niet tussen aanhalingstekens en niet met een afsluitende nieuwe regel die sommige frameworks standaard toevoegen.
Als het token niet overeenkomt, antwoord je met 403. Dat is het hele protocol, en het is bewust klein gehouden.
Waarom faalt een fout antwoord stil?
Omdat een mislukte verificatie geen fout in jouw systeem is, maar een ontbrekende stap in dat van Meta.
Wanneer de challenge niet correct wordt teruggestuurd, begint Meta simpelweg niet met leveren aan die bestemming. Je server stuurt 200 terug op de verificatie, je logboeken tonen dat er een verzoek is aangekomen en geen enkel dashboard meldt een probleem. Het enige symptoom is dat berichten nooit aankomen. De meeste mensen diagnosticeren dat als een Coexistence-probleem en niet als een handshakeprobleem.
Daarom is vooraf valideren de moeite waard. We controleren vóór het Graph-verzoek of de URL HTTPS gebruikt en of er een verify-token is opgegeven. Zo faalt een ongeldige bestemming direct, in plaats van verbonden te lijken.
Wat kan de verificatie nog blokkeren?
Drie dingen die niets met de code te maken hebben.
Authenticatie vóór het endpoint. Een gateway, een basic-authlaag of een IP-allowlist wijst Meta's verzoek af, en Meta kan geen inloggegevens meesturen. De verificatieroute moet zonder die gegevens bereikbaar zijn.
Een omleiding. Meta roept de URL aan die je hebt opgegeven, en een 301 naar een canonieke host wordt niet op een manier gevolgd die de handshake voltooit. Geef de definitieve URL op.
En een framework dat het antwoord serialiseert. Als een handler een tekenreeks terugstuurt en alles in JSON verpakt, bevat de body aanhalingstekens rond de challenge. Daardoor komt die niet overeen.
Veelgemaakte fouten
- JSON terugsturen. De body moet de ruwe challengewaarde zijn, zonder iets eromheen.
- Het endpoint achter authenticatie plaatsen. Meta heeft geen inloggegevens en wordt afgewezen.
- Meta een URL geven die omleidt. Gebruik de definitieve URL.
EasyCoexistence controleert vóór het aanroepen van Meta of een bestemming HTTPS gebruikt en een verify-token heeft. Een mislukte handshake wordt op de verbindingstijdlijn vastgelegd.
Veelgestelde vragen
Welk token moet ik gebruiken?
Elke tekenreeks die je kiest. Zo kan je endpoint Meta's verzoek onderscheiden van dat van iemand anders die de URL kent.
Hoe vaak vindt verificatie plaats?
Bij het instellen en opnieuw wanneer de bestemming wordt ingesteld. Een werkend endpoint wordt niet bij elk event opnieuw geverifieerd.
Kan ik het zelf testen?
Ja. Roep je eigen endpoint aan met de drie parameters en controleer of de body exact als de challengewaarde terugkomt.
Wat als mijn server tijdens de verificatie offline was?
De handshake mislukt en de bestemming wordt niet geactiveerd. Als je die opnieuw opslaat, wordt de verificatie opnieuw uitgevoerd.
Lees verder
Klaar om te beginnen?
Stel WhatsApp Coexistence in enkele minuten in, niet maanden. De app blijft op je telefoon werken.
Start je gratis proefperiodeGeverifieerd op