Een webhook stuurt een bericht naar een adres van jezelf zodra er iets gebeurt in je werkruimte, bijvoorbeeld als een bestelling is betaald of een abonnement is opgezegd. Zo houd je een ander systeem synchroon, zoals een tool als Zapier, je boekhouding of je eigen server.
Voordat je begint
De pagina staat onder Betalingen > Instellingen > Webhooks, in de groep Ontwikkelaars. Om de pagina te bekijken heb je Betalingen bekijken nodig. Endpoints toevoegen, wijzigen, testen en verwijderen vraagt Bestellingen / klanten bijwerken.
Een endpoint toevoegen
Klik op de knop om toe te voegen. Het venster Webhookendpoint toevoegen opent:
- Geef onder Endpoint eventueel een Naam op en vul de Endpoint-URL in. Het adres moet bereikbaar zijn vanaf het internet. Adressen in een privénetwerk worden geweigerd.
- Kies onder Evenementen wat het endpoint moet ontvangen. Gebeurtenissen zoeken maakt de lijst korter, het selectievakje van een groep selecteert de hele groep, en Alles selecteren of Alles wissen wijzigt alles in één keer. Er is minstens één gebeurtenis nodig.
- Klik op Aanmaken.
De gebeurtenissen zijn per onderwerp gegroepeerd:
- Betalingen: Bestelling betaald, Betaling wordt verwerkt, Betaling mislukt, Factuur betaald, Terugbetaling aangemaakt.
- Abonnementen: Abonnement aangemaakt, Abonnement verlengd, Abonnement opgezegd, Abonnementsbetaling mislukt.
- Leden: registraties, inlogs, toegevoegde of verwijderde tags, gewijzigde ledenvelden en nieuwe contacten.
- Cursussen en evenementen, Community en Data en inbox: afgeronde cursussen en lessen, aanmeldingen voor en aanwezigheid bij evenementen, berichten, niveaus, badges, inboxberichten en supportverzoeken.
- Partner: nieuwe commissies en betaalde uitbetalingen, zie de hulp bij het partnerprogramma.
Het ondertekeningsgeheim
Direct nadat je het endpoint hebt aangemaakt, toont de werkruimte het ondertekeningsgeheim één keer: Kopieer nu je ondertekeningsgeheim. Bewaar het aan jouw kant en klik dan op Klaar. Het wordt niet opnieuw getoond.
Elke levering wordt als JSON verstuurd met de header X-Maio-Signature. Daarin
staat een HMAC-SHA256 van de ruwe request-body, gemaakt met je geheim, als hex
in kleine letters. Bereken dezelfde waarde aan jouw kant en vergelijk ze, zo
weet je dat het bericht uit je werkruimte komt. De headers X-Maio-Event en
X-Maio-Delivery noemen de gebeurtenis en de levering.
Om het geheim te vervangen open je het endpoint en klik je op Geheim vernieuwen. Het oude geheim werkt direct niet meer, dus werk je endpoint meteen bij.
Testen
Open het endpoint en klik op Test sturen. De knop verandert in Test in wachtrij, en binnen enkele ogenblikken komt er een testgebeurtenis aan op je endpoint. Die verschijnt in het leveringslogboek zoals elke andere levering.
Het leveringslogboek
Het tabblad Leveringslogboek toont elke levering met de Gebeurtenis, het Endpoint, de Status, de HTTP-status waarmee je endpoint antwoordde, de Pogingen en Wanneer. Filter op Afgeleverd, Mislukt of In afwachting. Het onderdeel Leveringen van een endpoint toont de 20 recentste leveringen, met de foutmelding van elke mislukte levering.
Een levering telt als afgeleverd als je endpoint binnen 15 seconden met een 2xx-status antwoordt. Anders wordt ze opnieuw geprobeerd na 30 seconden, 5 minuten, 30 minuten, 2 uur en 6 uur. Opnieuw sturen verstuurt een levering nog een keer met dezelfde inhoud.
Na 20 mislukte pogingen op rij voor een gebeurtenis wordt die gebeurtenis voor het endpoint uitgeschakeld. Antwoordt het endpoint met 410 Gone, dan wordt de gebeurtenis meteen uitgeschakeld. Herstel het endpoint en zet het daarna weer op Actief.
Uitschakelen en verwijderen
In het endpoint wisselt de schakelaar tussen Actief en Uitgeschakeld. Een uitgeschakeld endpoint ontvangt niets. Verwijderen verwijdert het met al zijn gebeurtenissen nadat je dat hebt bevestigd.
Via de API
Apps die via de API zijn gekoppeld, kunnen hun eigen endpoints aanmaken met de
endpoints onder /api/v1/hooks en een API-sleutel met de scope
webhooks:manage. Ze verschijnen in de lijst met een badge API, en hier
kun je alleen hun naam en status wijzigen. Ze hebben geen Geheim vernieuwen
en geen Test sturen. Zie
API-sleutels en toegang voor ontwikkelaars.