Wat is een webhook? Zo werken webhooks in sona.to

Een webhook is een bericht dat de ene app naar de andere stuurt op het moment dat er iets gebeurt, zodat de tweede app niet steeds hoeft te vragen. Je geeft de eerste app een adres, en die stuurt de details van elke gebeurtenis daarheen zodra die plaatsvindt. Deze gids legt uit hoe webhooks werken, hoe je controleert of een webhook echt is en wat sona.to verstuurt, ook samengevat op de pagina over webhooks.

Wat is een webhook?

De meeste apps wisselen op twee manieren gegevens uit. Met een API vraagt jouw systeem: "is het bericht al gepubliceerd?", en vraagt het later opnieuw als het antwoord nee is. Met een webhook laat de app het jou weten: zodra het bericht is gepubliceerd, stuurt de app een verzoek naar een adres dat je hebt gekozen, met de details van het bericht.

Een webhook is dus een HTTP-verzoek, meestal een POST met een JSON-body, verstuurd naar een URL die jij beheert. Die URL kan je eigen server zijn, of een webhookadres van n8n, Zapier, Make, Slack of een andere dienst die een workflow start wanneer het verzoek binnenkomt.

Webhook of API

Een API is om te vragen en te wijzigen: berichten opvragen, een bericht maken, cijfers lezen. Een webhook is om op de hoogte gebracht te worden. De meeste integraties gebruiken allebei: de API om een bericht te maken en een webhook om te horen wanneer het is gepubliceerd of mislukt. Steeds opnieuw een API bevragen verspilt verzoeken en levert het nieuws toch laat op, terwijl een webhook binnenkomt zodra de gebeurtenis plaatsvindt.

Zo controleer je een webhook

Iedereen die je webhookadres kent, zou er een nepverzoek naartoe kunnen sturen, dus een goed gemaakte webhook is ondertekend. De afzender berekent een handtekening uit de body en een gedeeld geheim, meestal met HMAC SHA-256, en zet die in een header. Jouw kant berekent dezelfde handtekening met hetzelfde geheim en vergelijkt de twee met een vergelijking in constante tijd. Wijken ze af, dan wordt het verzoek genegeerd.

Een tijdstempel in de ondertekende gegevens voorkomt bovendien replay-aanvallen: een verzoek dat één keer is onderschept, kan later niet opnieuw worden verstuurd, omdat de tijdstempel te oud is.

Webhooks in sona.to

sona.to verstuurt webhooks voor vier gebeurtenissen: een bericht is gepubliceerd, een bericht is mislukt, een site-audit is klaar en een site-audit is mislukt. Je kiest welke gebeurtenissen elke webhook ontvangt, zodat een chatmelding alleen op fouten kan letten terwijl een rapportageblad alles binnenkrijgt. De payload gebruikt dezelfde veldnamen als de API van sona.to.

Instellen. Plak op de API-pagina van je dashboard het adres, vink de gebeurtenissen aan en sla op. Het ondertekeningsgeheim wordt alleen op dat moment één keer getoond, dus kopieer het dan.

Handtekening. Elke levering heeft een header met een tijdstempel en een HMAC SHA-256 van de tijdstempel en de body, gemaakt met jouw geheim. Weiger verzoeken waarvan de tijdstempel meer dan een paar minuten oud is.

Nieuwe pogingen. Is je adres onbereikbaar of geeft het een fout terug, dan wordt de levering opnieuw geprobeerd na 60 seconden, 5 minuten en 30 minuten. Elke poging wordt gelogd met de statuscode en de duur. Een adres dat blijft mislukken, wordt uitgeschakeld, en je kunt het weer aanzetten zodra het is opgelost.

Veiligheid. Het adres moet https gebruiken en naar een openbare server wijzen. Adressen op privénetwerken worden geweigerd bij het opslaan en opnieuw bij de levering, en doorverwijzingen worden niet gevolgd.

Webhooks met n8n, Zapier en Make

De sona.to-apps voor n8n, Zapier en Make hebben kant-en-klare triggers voor dezelfde vier gebeurtenissen, dus je hoeft zelf geen adres te plakken: voeg de trigger toe en de app stelt de webhook in. Zie social media automatisering met n8n, Zapier en Make.

Alle details, met een voorbeeld van een handtekeningcontrole, staan in de API-documentatie.

Veelgestelde vragen

Is een webhook hetzelfde als een API?

Nee. Een API antwoordt wanneer je iets vraagt. Een webhook stuurt je een bericht wanneer er iets gebeurt.

Zijn de webhooks van sona.to gratis?

Webhooks zitten in elk abonnement, samen met de API.

Wat gebeurt er als mijn server onbereikbaar is?

sona.to probeert het in ongeveer een half uur nog drie keer. Blijven de leveringen mislukken, dan wordt de webhook uitgeschakeld tot je hem weer aanzet.