Met webhooks stuurt Sonar gebeurtenissen door naar een adres dat jij kiest: een n8n- of Make-workflow, een catch hook in Zapier of je eigen software. Denk aan een gewonnen deal, een nieuw abonnement of een nieuwe lead. Elke levering is ondertekend en staat in een leveringslog.
Een endpoint instellen
- Ga naar Instellingen, Webhooks. Je hebt de rol eigenaar of beheerder nodig.
- Voeg een endpoint toe met het adres waar de webhook naartoe moet en kies de gebeurtenissen.
- Kopieer het geheim (begint met
whsec_). Je ziet het maar één keer. - Klik op Test versturen om een voorbeeld van een gebeurtenis te sturen en het antwoord te zien.
Wat je ontvangt
Elke levering is één POST met JSON. Het bericht bevat onder meer:
id: uniek per gebeurtenis. Bij een nieuwe poging blijft het gelijk, dus gebruik het om dubbele verwerking te voorkomen.event: de gebeurtenis, bijvoorbeelddeal.won.occurred_at: wanneer het gebeurde.subjectendata: over welk record het gaat en de gegevens op dat moment.
Alleen een antwoord in de 2xx-reeks telt als geleverd. Antwoord snel en doe het werk daarna. Doorverwijzingen worden niet gevolgd: gebruik het uiteindelijke adres.
De handtekening controleren
Elke levering heeft een header X-Sonar-Signature in de vorm t=. Controleer hem zo:
- Lees de ruwe body, voordat je de JSON verwerkt.
- Bereken een HMAC-SHA256 van
tijd + "." + bodymet je geheim. - Accepteer de levering als de uitkomst gelijk is aan een van de
v1-waarden en de tijd niet ouder is dan 5 minuten.
In n8n
- Zet in de Webhook-node de methode op
POSTen schakel onder Options Raw Body in. - Zet een Code-node erachter die de handtekening controleert. Gooi een fout als hij niet klopt.
- Zet in de Webhook-node Respond op “When Last Node Finishes”. Dan ziet Sonar een fout als de controle faalt, in plaats van een
200vooraf. - De Code-node heeft de module
cryptonodig: zetNODE_FUNCTION_ALLOW_BUILTIN=cryptoop je n8n-installatie.
Als een levering mislukt
Sonar probeert het tot zes keer: direct, en daarna na 1 minuut, 5 minuten, 30 minuten, 2 uur en 6 uur. In het leveringslog kun je een mislukte levering opnieuw versturen. Na 50 mislukte leveringen achter elkaar wordt het endpoint uitgeschakeld en krijgen eigenaren en beheerders een melding.
De volgorde van leveringen is niet gegarandeerd. Gebruik occurred_at als volgorde belangrijk is.
Je geheim vervangen
Maak je een nieuw geheim, dan blijft het oude nog 24 uur geldig. In die periode bevat de header twee handtekeningen. Zet het nieuwe geheim binnen die dag in je ontvanger.