Webhooks #

Met webhooks kan Your AI Connector uw andere zakelijke tools automatisch op de hoogte stellen wanneer er iets belangrijks gebeurt — zoals het aanmaken van een nieuw contact, het boeken van een afspraak of het ontvangen van een bericht. In plaats van handmatig op updates te controleren, ontvangen uw gekoppelde systemen direct een melding zodra er iets gebeurt.

Wat zijn webhooks? #

Zie een webhook als een automatisch sms-bericht tussen twee apps. Wanneer er iets gebeurt in Your AI Connector (zoals een nieuwe aanmelding van een contact), stuurt het platform direct een melding naar een ander systeem naar keuze. U geeft een webadres op (een “webhook-URL”) waar deze meldingen naartoe moeten worden gestuurd — dit wordt meestal verstrekt door uw CRM, automatiseringsplatform of ontwikkelaar.

Webhooks sturen alleen gegevens UIT Your AI Connector. Een webhook is een eenrichtingsverkeer van Your AI Connector naar je andere tools. Er is geen webhook-URL die leads, contacten of berichten HET platform IN stuurt. Om een nieuwe lead toe te voegen — vanuit een websiteformulier, je CRM of GoHighLevel — maakt je systeem in plaats daarvan een API-aanroep. Zie API-toegang (de Create a Contact-bewerking) en Funnels. Het enige wat je nodig hebt voor de inkomende richting is je API-sleutel, die in zijn eigen sectie staat — zie API-toegang. De pagina Webhooks die hier wordt beschreven, is uitsluitend bedoeld voor de uitgaande richting.

Veelvoorkomende toepassingen zijn:

• Nieuwe contacten synchroniseren met je CRM.
• Een workflow activeren in Zapier, Make of Pabbly wanneer een tag wordt toegevoegd.
• Je team in Slack op de hoogte stellen wanneer een menselijke tussenkomst is vereist.
• Je agendasysteem bijwerken wanneer een afspraak is geboekt.
• Gesprekssamenvattingen loggen in je database.

Webhooks instellen #

1. Klik in de linkerzijbalk op Instellingen (tandwielpictogram).
2. Klik in de zijbalk Instellingen, onder de groep Integraties, op Webhooks.

Op een account waar nog geen webhooks zijn geconfigureerd, ziet de pagina er als volgt uit:

3. Klik rechtsboven op New webhook. Er wordt een formulier geopend op de pagina:

4. Vul het volgende in:
   • Endpoint-URL — het webadres waar Your AI Connector gebeurtenismeldingen naartoe zal sturen. U krijgt dit van uw externe systeem (CRM, automatiseringsplatform of eigen server).
   • Naam — een label dat u later zult herkennen (bijv. “Slack-meldingen” of “CRM-synchronisatie”). Alleen voor uw eigen referentie.

Je webhook-URL moet een publiek bereikbaar https://-adres zijn. Gewone http://-adressen, localhost- of privénetwerkadressen en interne platformadressen worden geweigerd bij het opslaan. Gebruik voor het testen vanaf je eigen machine een publieke tunnel (webhook.site of ngrok) in plaats van localhost.

5. Klik onder Events op de gebeurtenissen die deze webhook moet ontvangen — alle 22 staan vermeld in The 22 Webhook Events.
6. (Optioneel) Schakel Retry failed deliveries in als je wilt dat Your AI Connector opnieuw probeert te verzenden bij een tijdelijke fout — zie Retrying Failed Deliveries.
7. Klik op Create webhook. Deze verschijnt in de lijst onder het formulier en je kunt op elk gewenst moment op Test in de rij klikken om een voorbeeld-payload naar je eindpunt te sturen.

Toestemming vereist. Voor het toevoegen, bewerken of testen van webhooks is de “bewerken”-toestemming voor Integraties vereist (teamleden met alleen-lezen toegang zien een melding dat het formulier alleen-lezen is).

Het ondertekenen van een webhook vereist dat deze eerst is opgeslagen — open de rij van een bestaande webhook om deze te bewerken, en het paneel Ondertekeningsgeheim verschijnt onderaan het bewerkingsformulier. Een gloednieuw, niet-opgeslagen concept heeft nog geen ondertekeningsoptie — zie Ondertekende payloads hieronder.

Eén webhook voor al uw klantaccounts (bureaus) #

Als u een bureau runt, hoeft u niet voor elk klantaccount opnieuw dezelfde webhook aan te maken. Op het bureau-account heeft het webhook-formulier een extra schakelaar: Ook activeren voor alle klantaccounts. Schakel deze in en deze webhook ontvangt ook events die plaatsvinden op elk klantaccount onder uw bureau — één endpoint, het hele bureau.

Hoe het werkt:

• Het user-blok vertelt u bij welke klant een event hoort. Elke notificatie bevat al een user-blok dat het account identificeert waarop het event heeft plaatsgevonden, zodat uw automatisering per klant kan routeren.
• De instellingen van uw webhook zijn overal van toepassing. De events die u heeft geselecteerd, het ondertekeningsgeheim en de instelling voor opnieuw proberen worden ook gebruikt voor leveringen aan klantaccounts.
• Geen dubbele leveringen. Als een klantaccount een eigen webhook heeft die naar dezelfde URL wijst, wordt die gebruikt voor de events van dat account — hetzelfde event komt nooit twee keer aan op één endpoint.
• Klanten zien het niet. De webhook verschijnt niet op de eigen Webhooks-pagina van het klantaccount en klanten kunnen deze niet uitschakelen — het is aan u om deze te beheren.
• Betrouwbaarheid wordt per klantaccount bijgehouden. Als uw endpoint blijft falen, wordt het automatisch uitgeschakeld voor het account waarvan de leveringen zijn mislukt (zie Webhook-betrouwbaarheid), en niet voor het hele bureau tegelijk.

De schakelaar verschijnt alleen bij bureau-accounts. Het instellen hiervan via de API wordt ook ondersteund — zie het apply_to_sub_accounts-veld in de Webhooks API.

Beschikbare triggergebeurtenissen #

Je kunt elk van de 22 webhook-gebeurtenissen onafhankelijk in- of uitschakelen. Wanneer een gebeurtenis wordt geactiveerd, stuurt Your AI Connector een melding naar je webhook-URL met de relevante gegevens. Elke gebeurtenis, wat deze betekent en de event-code die in de payload wordt geplaatst, staan samen vermeld in The 22 Webhook Events verderop op deze pagina.

Goed om te weten: Task Created, Task Updated en Task Completed zijn volledig selecteerbaar en worden correct opgeslagen. Daily Summary Created is ook een recente toevoeging. Zie Task Completed Webhook hieronder voor de vorm van die payload.

Webhook-triggers op basis van tags #

subscribed_to_tags koppelt de gebeurtenissen van een webhook niet aan een tag. Het beperkt alleen welke tags een melding voor een gespreks-samenvatting genereren. Om een verzoek te ontvangen wanneer een specifieke tag wordt toegepast, stel je een webhook-URL in op die tag in het tabblad Tags van de agent (of campagne).

Het webhook-formulier zelf heeft geen tag-kiezer, noch bij het maken van een nieuwe webhook, noch bij het bewerken ervan, dus subscribed_to_tags kan alleen worden gelezen of gewijzigd via de Webhooks API, of door ondersteuning te vragen.

Goed om te weten: het bewerken van een bestaande webhook die een subscribed_to_tags-lijst heeft (hernoemen, gebeurtenissen wijzigen, opnieuw proberen in-/uitschakelen) wist die lijst niet langer — aangezien het formulier geen tag-kiezer heeft om terug te sturen, laat het opslaan vanaf deze pagina de bestaande lijst nu ongemoeid. (Dit was een echte bug vóór 21 juli 2026: opslaan vanuit het webhook-formulier wist voorheen de lijst omdat er altijd een lege tag-lijst werd verzonden. Als een webhook vóór die datum zijn subscribed_to_tags-lijst is verloren, moet deze opnieuw worden geconfigureerd via de API.)

Samenvatting genereren voor getagde contactpersonen #

Waar een webhook een subscribed_to_tags-lijst heeft, kun je Generate Summary inschakelen. Wanneer dit is ingeschakeld, genereert Your AI Connector automatisch een gespreks-samenvatting voor de contactpersoon wanneer een van die tags wordt toegepast, en neemt deze op in de webhook-gegevens — volledige context zonder een apart verzoek.

Je webhook testen #

1. Open Instellingen → Integraties → Webhooks.
2. Klik op Test op de rij van uw webhook.
3. Controleer uw externe systeem om te bevestigen dat de testgegevens zijn ontvangen.
4. Controleer de gegevensindeling om er zeker van te zijn dat uw systeem deze correct kan verwerken.

Voor een volledige end-to-end test verstuurt u een bericht dat een van uw geconfigureerde gebeurtenissen zou activeren (een broadcast of een inkomend bericht op een verbonden kanaal) en controleert u of de webhook wordt geactiveerd met de echte gegevens.

Wat telt als een succesvolle bezorging #

Of je nu op Test klikt of de gebeurtenis echt wordt geactiveerd, we sturen hetzelfde:

• Een POST-verzoek (nooit GET), met de body als JSON en Content-Type: application/json.
• De headers vermeld onder Signed Payloads. Handtekening-headers worden pas toegevoegd zodra je een ondertekeningsgeheim hebt ingesteld.

We beschouwen de bezorging als succesvol wanneer:

• Je endpoint antwoordt met een 2xx-status (200, 201, 204 — allemaal prima).
• Het antwoord binnen 30 seconden binnenkomt.

Een paar dingen die mensen verrassen:

• De response body wordt genegeerd. U hoeft geen specifieke JSON terug te sturen. Een lege 200 is voldoende.
• Omleidingen tellen als een fout. We volgen deze niet, dus een 301 of 302 (inclusief een omleiding voor een afsluitende slash, of http naar https) wordt geregistreerd als een mislukte aflevering. Sla de uiteindelijke URL op, niet een die omleidt.
• Query strings worden volledig ondersteund. https://your-app.com/hook?token=abc123 wordt exact zo verzonden als u deze heeft opgeslagen, dus een token in de query string plaatsen werkt net zo goed als in het pad.
• Uw URL moet https:// zijn en publiekelijk bereikbaar. Adressen die toebehoren aan de eigen infrastructuur van Your AI Connector worden geweigerd, maar uw eigen eindpunten op Google Cloud Functions, Cloud Run, App Engine, Firebase Hosting of elders zijn prima.
• Een firewall of bot-beveiligingslaag voor uw eindpunt kan ons blokkeren. Het meest voorkomende geval is Cloudflare: als uw zone Bot Fight Mode of een beheerde uitdaging aan heeft staan, krijgt ons verzoek een “Just a moment…” uitdagingspagina met een 403 in plaats van dat het uw server bereikt — en een server-naar-server verzoek kan nooit een browser-uitdaging passeren, dus zowel de Test-knop als echte gebeurtenissen falen op dezelfde manier. De Test-knop zal u vertellen wanneer dit gebeurt (“Cloudflare is showing a bot challenge to our request”). Los dit op in Cloudflare met een Security / WAF-regel die uitdagingen overslaat voor uw webhook-pad (of voor de Webhook-Delivery/1.0 user agent), en klik daarna opnieuw op Test.
• Als uw firewall in plaats daarvan een IP-toelatingslijst nodig heeft (bijvoorbeeld het gratis abonnement van Cloudflare, waar de standaard Bot Fight Mode niet kan worden overgeslagen door een WAF-regel, maar een IP Access Rule ingesteld op Allow wel voorrang krijgt), kunnen we helpen: elke aflevering, of deze nu via de Test-knop of een live gebeurtenis komt, wordt verzonden vanaf één vast IPv4-adres (geen bereiken, geen IPv6, geen rotatie). Neem contact op met de ondersteuning en wij geven u het adres dat u op de toelatingslijst kunt zetten. Houd handtekeningverificatie aan als uw daadwerkelijke vertrouwenscontrole, aangezien deze elke payload valideert, ongeacht waar deze vandaan komt.
• Het testresultaat vertelt u precies wat uw eindpunt heeft geantwoord. Een mislukte test toont nu de werkelijke reden (de HTTP-status die uw eindpunt heeft geretourneerd, een time-out, of dat we het adres helemaal niet konden bereiken) in plaats van een algemene foutmelding, en een test op een opgeslagen webhook wordt ondertekend verzonden wanneer ondertekening is ingeschakeld, precies zoals bij een live gebeurtenis.

n8n, Make of Zapier gebruiken (“Test-URL” vs “Productie-URL”) #

Automatiseringsplatforms geven je meestal twee verschillende webhook-adressen, en dit brengt mensen vaak in verwarring:

• Een Test-URL (in n8n bevat deze /webhook-test/). Deze ontvangt alleen gegevens terwijl u actief naar het canvas kijkt en zojuist op Listen for test event (of Test workflow) hebt geklikt. Het legt één gebeurtenis vast en stopt dan met luisteren — dus meerdere keren achter elkaar op Test klikken in Your AI Connector vangt alleen de eerste op, en alleen als het luistervenster op dat exacte moment actief is. Om te testen: klik eerst op Listen for test event in n8n, ga dan terug naar Your AI Connector en klik één keer op Test.
• Een Productie-URL (in n8n bevat deze /webhook/, geen -test). Dit is de URL die u in Your AI Connector moet plakken voor live-gebeurtenissen. Deze werkt pas zodra uw workflow op Active is gezet. Als de workflow niet actief is, weigert n8n het verzoek met een “404 / webhook not registered”-fout, ook al heeft Your AI Connector de gegevens correct verzonden.

Kortom: test met de Test-URL terwijl je luistert, maar om de webhook te laten werken voor echte contacten, sla je de Productie-URL op in Your AI Connector en zorg je ervoor dat de workflow Active is.

Gegevensindeling van de webhook #

Wanneer een webhook wordt geactiveerd, stuurt Your AI Connector gestructureerde gegevens (JSON) naar uw webhook-URL. Als u een automatiseringsplatform zoals Zapier of Make gebruikt, worden deze gegevens automatisch voor u geparseerd. Als u een aangepaste integratie bouwt:

{
  "event": "contactCreated",
  "contact": { "id": "<contact-id>", "first_name": "Jane", "...": "..." },
  "campaign": { "id": "<campaign-id>", "name": "AI Receptionist", "status": "Live" },
  "agent": { "id": "<agent-id>", "name": "Front Desk" },
  "user": { "id": "<account-id>", "email": "owner@example.com" }
}

campaign of agent — meestal één, niet beide. Als uw account gebruikmaakt van agents, worden uw contactpersonen toegewezen aan een agent in plaats van aan een campagne, dus campaign komt binnen als null en agent vertelt u wie het heeft afgehandeld. Oudere accounts op basis van campagnes zien het omgekeerde. Lees wat er is ingevuld; ga er niet vanuit dat campaign altijd aanwezig is.

Het agent-blok is gearriveerd op 15 augustus 2026. Het bevindt zich naast campaign bij de gebeurtenissen die gekoppeld zijn aan een gesprek — een afgesloten chat, niet storen, een hervatting, een de-archivering, een AI-pauze, een nieuw bericht, een gespreks-samenvatting en de webhook die je kunt instellen op een tag — en bevat de id en name van de afhandelende agent, of null wanneer er geen agent bij betrokken is. Het is puur toevoegend: elk veld dat je al ontvangt blijft ongewijzigd, dus een ontvanger die je vóór die datum hebt gebouwd, blijft werken zonder dat er iets bijgewerkt hoeft te worden.

Sommige gebeurtenissen voegen hun eigen extra blok op het hoogste niveau toe. Bijvoorbeeld: Afspraak geboekt voegt een appointment-blok toe (zie Webhook voor afspraak geboekt), Nieuw bericht voegt een volledig message-blok toe met de tekst (zie Webhook voor nieuw bericht), en Afleveringen en Lezingen voegen een kort message-blok toe met alleen het ID en de status van het bericht (zie Webhook voor afleveringen en lezingen).

Afleveringen en lezingen vertellen je om welk bericht het gaat, maar niet wat erin stond. Ze bevatten een message-blok met het id en status van het bericht — en dat id is hetzelfde messageId als wat het eindpunt voor berichtverzending teruggeeft, zodat je een aflever- of leesbevestiging kunt koppelen aan het exacte bericht dat je hebt verzonden — maar zonder berichtinhoud. Antwoorden bevat helemaal geen message-blok. Als je de woorden wilt weten die zijn verzonden of ontvangen, abonneer je dan daarnaast op Nieuw bericht.

Twee dingen om te weten voordat u uw ontvanger schrijft. Er is geen timestamp-veld en geen data-wrapper. Elk blok bevindt zich op het hoogste niveau van het JSON-object, zoals hierboven getoond.

The 22 Webhook Events #

De 22 webhook-gebeurtenissen, met het weergavelabel dat je in de app aanvinkt en de event-code die in de payload wordt verzonden. De event-code is een korte string die niet overeenkomt met het weergavelabel, dus laat je ontvanger matchen op de code, niet op het label:

Nog twee codes verschijnen nooit in die lijst omdat je je er niet op abonneert: contact_tags_updated, verzonden door een webhook-URL ingesteld op een individuele tag, en summary_generated, verzonden wanneer een chatsamenvatting wordt geschreven voor een tag in de subscribed_to_tags-lijst van een webhook.

Kanaal verbonden wordt nog niet verzonden. Het verschijnt in de lijst met gebeurtenissen, maar er is momenteel niets dat dit activeert. Bouw hier niet op.

Notificaties op basis van tags en taken gebruiken hun eigen aparte vormen. Zie Contact Tags Updated en Task Completed.

Webhook Contact aangemaakt #

Wordt verzonden wanneer de gebeurtenis Contact aangemaakt wordt geactiveerd (een nieuw contact wordt handmatig, via import of via API toegevoegd).

Gebeurtenisnaam #

contactCreated

Payload-indeling #

{
  "event": "contactCreated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}

Het “Test”-voorbeeld en een echte gebeurtenis zien er iets anders uit. De testknop verstuurt tijdelijke gegevens (John Doe, een voorbeeldcampagne). Een echte gebeurtenis voor het aanmaken van een contact bevat de details van het werkelijke contact, en sommige velden kunnen leeg zijn, afhankelijk van het kanaal.

Nieuw bericht-webhook #

Deze webhook wordt geactiveerd telkens wanneer er een bericht wordt toegevoegd aan een gesprek, op welk kanaal dan ook. Het omvat beide richtingen: berichten die uw contact naar u stuurt, en berichten die uw AI, uw team of een campagne naar hen stuurt. Het is de enige webhook die de berichttekst bevat, dus dit is de webhook die u moet gebruiken wanneer u gesprekken wilt spiegelen naar een extern systeem.

Gebeurtenisnaam #

new_message

Payload-indeling #

{
  "event": "new_message",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "body": "Hi, are you open on Saturday?",
    "direction": "inbound",
    "status": "received",
    "created_at": "2026-07-30T17:27:06.000Z",
    "channel": "whatsapp_web"
  }
}

Er is nog steeds geen campaign-blok in deze payload. New Message verzendt contact, agent, user en message. Het agent-blok is toegevoegd op 15 augustus 2026 en vertelt je welke agent het gesprek afhandelt; als je ook campagnecontext nodig hebt, zoek de contactpersoon dan op via de API met contact.id.

Interne AI-records activeren deze webhook niet. Naast echte berichten houdt het platform zijn eigen boekhoudkundige rijen bij in een gesprek (de tool-aanroepen van de AI en interne turn-records). Deze worden nooit verzonden — u ontvangt alleen berichten die daadwerkelijk zijn verzonden of ontvangen.

Webhook voor afleveringen en lezingen #

Deze twee gebeurtenissen rapporteren wat er met een bericht is gebeurd nadat het Your AI Connector heeft verlaten: Afleveringen wordt geactiveerd wanneer een bericht het contact bereikt (of niet), en Lezingen wordt geactiveerd wanneer het contact het opent, op de kanalen die leesbevestigingen ondersteunen.

Beide bevatten een message-blok met het ID van het bericht waar de gebeurtenis over gaat, zodat je de update kunt koppelen aan het exacte bericht dat je hebt verzonden.

Gebeurtenisnamen #

delivered en undelivered voor Afleveringen, read voor Lezingen.

Payload-indeling #

{
  "event": "delivered",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "ad_referral": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "status": "delivered"
  }
}

Hoe koppel je een update aan het bericht dat je hebt verzonden. Sla het messageId op dat je terugkrijgt wanneer je een bericht via de API verzendt. Wanneer er een Afleveringen- of Lezingen-melding binnenkomt, zoek dan dat opgeslagen ID op in message.id in de payload — dat is je aflever- of leesbevestiging voor dat specifieke bericht.

Er is hier geen berichttekst. Het message-blok bevat alleen het ID en de status. Abonneer je op Nieuw bericht als je ook de inhoud nodig hebt.

Het message-blok is alleen aanwezig wanneer we weten om welk bericht het ging. Bij de zeldzame update die we niet kunnen koppelen aan een opgeslagen bericht, wordt het blok volledig weggelaten in plaats van leeg verzonden — controleer dus of message bestaat voordat je message.id leest.

Eén melding per statuswijziging. Een enkel uitgaand bericht produceert normaal gesproken een delivered-melding en vervolgens, op kanalen met leesbevestigingen, een read-melding. Een mislukte verzending produceert in plaats daarvan undelivered.

Appointment Booked Webhook #

Wordt geactiveerd wanneer een contact een afspraak boekt. Het wordt op dezelfde manier geactiveerd, of de AI het nu tijdens een gesprek heeft geboekt, u het handmatig hebt geboekt of het via de API is binnengekomen.

Gebeurtenisnaam #

booked

Payload-indeling #

{
  "event": "booked",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith"
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com"
  },
  "appointment": {
    "appointment_id": "<appointment-id>",
    "start_time": "2026-07-20T15:00:00.000Z",
    "end_time": "2026-07-20T15:30:00.000Z",
    "status": "confirmed",
    "room_name": "Room 1",
    "description": "Discovery call",
    "summary": "30 min intro",
    "google_calendar_event_id": null,
    "event": {
      "id": "<service-id>",
      "event_name": "Intro Call",
      "slot_duration": 30,
      "location": "Zoom",
      "meeting_link": "https://...",
      "event_type": "online"
    }
  }
}

google_calendar_event_id is vaak null in deze webhook, en dat is normaal. De Google Agenda-gebeurtenis wordt op hetzelfde moment aangemaakt als deze melding wordt verstuurd, dus het ID is meestal nog niet klaar. Haal de afspraak een moment later opnieuw op via het appointment_id als u het nodig heeft. Het blijft permanent null als het account geen Google Agenda heeft gekoppeld, dus wacht er niet eeuwig op.

De “Test”-knop bevat niet het appointment-blok. Gebruik deze om te bevestigen dat uw eindpunt antwoordt, en maak vervolgens één echte boeking om de volledige payload te zien.

Twee gevallen waarin deze webhook niet wordt geactiveerd: afspraken die zijn geïmporteerd vanuit een externe agenda, en boekingen die binnenkomen via de Formitable-integratie.

Webhook voor bijgewerkte contacttags #

Wordt geactiveerd wanneer een tag wordt toegepast op een contactpersoon, en die tag een webhook-URL heeft geconfigureerd op de agent of campagne waartoe de contactpersoon behoort.

Gebeurtenisnaam #

contact_tags_updated

Wanneer deze wordt geactiveerd #

• Er wordt een tag toegepast op een contactpersoon aan wie een agent is toegewezen, een campagne is toegewezen, of beide.
• Ten minste één van de toegepaste tags heeft een webhook-URL ingesteld in het tabblad Tags van die agent of campagne.

Als het contact beide heeft en de tags van de campagne webhook-URL’s bevatten, hebben die voorrang; anders worden die van de agent gebruikt.

Als er meerdere tags met verschillende webhook-URL’s in dezelfde update worden toegepast, wordt er één verzoek per URL verzonden, waarbij elk verzoek alleen de tags bevat die aan die URL zijn gekoppeld.

Het verwijderen van een tag verstuurt nooit een verzoek. De meeste mensen koppelen deze URL’s aan een actie — een aanbetaling innen, een tijdslot boeken, een medewerker waarschuwen — dus een tag die van een contactpersoon wordt verwijderd, werd voorheen gebruikt om die actie opnieuw uit te voeren. Dat kan niet meer. Een verwijdering verschijnt nog steeds in removed_tags wanneer dit gebeurt in dezelfde update als een toevoeging die naar dezelfde URL gaat, zodat een automatisering die beide arrays leest het volledige beeld behoudt; wat het nooit zal zien, is een verzoek dat uitsluitend door een verwijdering wordt veroorzaakt. (Gewijzigd op 12 augustus 2026. Vóór die datum verstuurden verwijderingen ook een verzoek.)

Payload-indeling #

{
  "event": "contact_tags_updated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "is_bot_active": true,
    "ad_referral": {
      "ctwa_clid": "ARAbc123...",
      "source_id": "120210000000000",
      "source_type": "ad",
      "source_url": "https://fb.me/xxxx",
      "headline": "Get 20% off today",
      "body": "Message us now to claim your discount",
      "channel": "whatsapp"
    }
  },
  "added_tags": ["qualified-lead"],
  "removed_tags": ["new-lead"],
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}

Een tag-webhook testen #

Naast het webhook-URL-veld op het tabblad Tags staat een Test-knop. Hiermee wordt direct een voorbeeldpayload naar die URL verzonden, zodat u kunt bevestigen dat uw automatisering deze ontvangt voordat u op een echt gesprek hoeft te wachten.

De test verzendt dezelfde contact_tags_updated-vorm als hierboven weergegeven, met gebruik van een tijdelijke contactpersoon, met de tag die u test in added_tags en een lege removed_tags. Wat uw automatisering in de test ziet, is wat deze in productie zal zien.

Twee dingen om te weten:

• Sla eerst de tag op. De test zoekt de tag op basis van de opgeslagen naam, dus een gloednieuwe tag of een niet-opgeslagen naamswijziging kan nog niet worden getest. De knop blijft grijs totdat de naam op het scherm overeenkomt met de opgeslagen naam.
• Een mislukte test telt niet mee voor je webhook. Tests dragen nooit bij aan de automatische uitschakeling na herhaalde fouten zoals beschreven in Webhook Reliability.

Als de test mislukt, vertelt het bericht u wat uw eindpunt heeft geantwoord (bijvoorbeeld een 404 of 500), wat meestal voldoende is om een verkeerde URL of een workflow die niet is ingeschakeld te identificeren.

Webhook voor voltooide taak #

Alleen ter referentie. Taak-webhooks (als gegevens) zijn hier gedocumenteerd voor ontwikkelaars; de gebeurtenissen Task Created, Task Updated en Task Completed zijn selecteerbaar in de standaard gebeurtenissenlijst op het webhook-formulier zoals elke andere gebeurtenis — zie Available Trigger Events en The 22 Webhook Events.

Deze payload wordt verzonden wanneer een taak overgaat naar een fase die is gemarkeerd als een voltooiingsfase. Een taak die tussen niet-voltooiingsfasen beweegt, verzendt in plaats daarvan de taskUpdated-vorm.

Gebeurtenisnaam #

taskCompleted

Wanneer deze wordt geactiveerd #

• Een taak wordt bijgewerkt.
• De stage-waarde is gewijzigd ten opzichte van de vorige waarde.
• De nieuwe fase is geconfigureerd als een voltooiingsfase in de taakfase-instellingen van het account.

Payload-indeling #

{
  "event": "taskCompleted",
  "contact": {
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<task-id>",
    "title": "Follow up with Jane",
    "description": "Confirm pricing and send proposal",
    "type": "follow_up",
    "priority": "high",
    "stage": "<stage-id>",
    "due_date": "2026-01-20T15:00:00Z",
    "source": "ai",
    "source_detail": "<source-detail>",
    "campaign_id": "<campaign-id>",
    "linked_human_alert": "<human-alert-id>",
    "tags": ["qualified-lead"],
    "notes": "Customer requested a callback"
  }
}

Een webhook uitschakelen (of verwijderen) #

Elke webhook heeft een aan/uit-schakelaar, direct op de rij. Het uitschakelen ervan stopt het ontvangen van gebeurtenissen, maar behoudt alles wat u heeft geconfigureerd — de URL, de gebeurtenissen, elk ondertekeningsgeheim. Schakel het weer in en het gaat verder waar het gebleven was; niets van wat er gebeurde terwijl het uitgeschakeld was, wordt achteraf afgeleverd.

Gebruik dit wanneer je wilt dat bezorgingen tijdelijk stoppen: je endpoint wordt opnieuw opgebouwd, je bent een drukke integratie aan het debuggen of je pauzeert een automatisering.

Het verwijderen van een webhook (het prullenbakpictogram op de rij) verwijdert deze definitief, inclusief het ondertekeningsgeheim. Als u alleen wilt dat de leveringen stoppen, schakel deze dan uit — verwijderen is voor wanneer u helemaal klaar bent met het eindpunt.

Dit is niet hetzelfde als het automatisch uitschakelen van een webhook. Als we je webhook uitschakelen na herhaalde fouten (zie Webhook-betrouwbaarheid), zal de bovenstaande schakelaar deze niet opnieuw inschakelen. Zodra je eindpunt is hersteld, bewerk je de webhook en sla je deze op met een gewijzigde URL (elke URL-wijziging schakelt deze opnieuw in), of roep je het opnieuw inschakelen-eindpunt aan via de API — of vraag ondersteuning en wij schakelen het weer voor je in.

Ondertekende Payloads (Verifiëren of een webhook echt van ons afkomstig is) #

Iedereen die uw webhook-URL leert kennen, kan er een nepverzoek naar sturen. Als u automatisch actie onderneemt op webhooks — zoals facturering bijwerken of CRM-records aanmaken — kunt u door ondertekening in te schakelen verifiëren dat elk verzoek daadwerkelijk van ons afkomstig is.

Ondertekening is optioneel en standaard uitgeschakeld, en u schakelt dit per webhook in vanuit de bewerkingsweergave van die webhook (open de rij van een opgeslagen webhook).

Ondertekening inschakelen #

1. Open de webhook (Instellingen → Integraties → Webhooks → klik op de rij van uw webhook).
2. Klik in het gedeelte Ondertekeningsgeheim op Genereren.
3. Kopieer het geheim (het begint met whsec_) en sla het op in uw ontvangende systeem. Behandel het als een wachtwoord.

U kunt op elk gewenst moment terugkeren naar dit paneel om het geheim te onthullen, kopiëren, roteren of uit te schakelen.

Wat we versturen #

Zodra ondertekening is ingeschakeld, bevat elke aflevering voor die webhook deze twee extra HTTP-headers:

Deze drie staan op elke aflevering, ondertekend of niet:

Hoe te verifiëren #

De handtekening is een HMAC-SHA256 van de string <timestamp>.<raw request body>, waarbij je ondertekeningsgeheim als sleutel wordt gebruikt.

Verifieer tegen de onbewerkte request body — de exacte bytes die u heeft ontvangen. Als uw framework de JSON parseert en opnieuw serialiseert voordat het controleert, kunnen de bytes veranderen en zal de handtekening niet overeenkomen.

Node.js-voorbeeld:

const crypto = require("crypto");

function verify(rawBody, headers, secret) {
  const timestamp = headers["x-webhook-timestamp"];
  const signature = headers["x-webhook-signature"]; // "v1=<hex>"

  // Reject anything older than 5 minutes so a captured request can't be replayed later.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");

  return crypto.timingSafeEqual(Buffer.from(signature.replace("v1=", "")), Buffer.from(expected));
}

Python-voorbeeld:

import hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers["X-Webhook-Timestamp"]
    signature = headers["X-Webhook-Signature"].replace("v1=", "")

    # Reject anything older than 5 minutes so a captured request can't be replayed later.
    if abs(time.time() - int(timestamp)) > 300:
        return False

    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()

    return hmac.compare_digest(signature, expected)

Vergelijk handtekeningen met een timing-safe functie (timingSafeEqual / compare_digest), niet ==. Het kost niets en voorkomt een subtiele klasse van aanvallen.

Het geheim roteren #

Klik op Roteer om het geheim te vervangen. De overschakeling is onmiddellijk: de eerstvolgende levering wordt alleen ondertekend met het nieuwe geheim. Als uw endpoint live is, accepteer dan gedurende enkele minuten zowel het oude als het nieuwe geheim terwijl u het nieuwe implementeert.

Het uitschakelen van ondertekening zorgt er simpelweg voor dat de ondertekeningsheaders niet langer worden verzonden.

Mislukte leveringen opnieuw proberen #

Standaard wordt een mislukte levering niet opnieuw geprobeerd — als uw systeem op dat moment offline is, gaat die gebeurtenis verloren.

Schakel Mislukte leveringen opnieuw proberen in voor een webhook (in het aanmaak-/bewerkingsformulier) en we blijven het proberen:

Dat beslaat ongeveer 2 uur en 40 minuten, waardoor een webhook een onderhoudsvenster of een korte storing aan uw kant kan overbruggen.

Wat wordt opnieuw geprobeerd: tijdelijke problemen — uw server die een 5xx-fout retourneert, een time-out of een verbindingsfout.

Wat niet wordt geprobeerd: als uw endpoint het verzoek zelf afwijst (elke 4xx), proberen we het niet opnieuw — het opnieuw versturen van hetzelfde verzoek zou alleen leiden tot dezelfde afwijzing.

Welke gebeurtenissen worden opnieuw geprobeerd: tag-webhooks (contact_tags_updated), de drie taakgebeurtenissen en het dagelijkse overzicht. De rest wordt één keer verzonden, dus daarvoor heeft de schakelaar geen functie. Elke gebeurtenis bevat nog steeds X-Webhook-Delivery, dus één ontdubbelingsregel dekt ze allemaal.

Schakel opnieuw proberen alleen in als uw endpoint idempotent is. Opnieuw proberen betekent dat hetzelfde evenement meer dan eens kan aankomen. Gebruik de X-Webhook-Delivery header om een herhaling te herkennen: deze blijft bij elke poging voor één evenement hetzelfde, zodat u veilig een ID kunt negeren dat u al heeft verwerkt.

Opnieuw proberen (retries) werkt samen met de automatische uitschakeling na herhaalde fouten (zie Webhook-betrouwbaarheid) precies zoals je zou willen: de foutteller telt een volledige aflevering pas nadat elke poging tot opnieuw proberen is verbruikt — niet elke individuele poging.

Betrouwbaarheid van webhooks #

• Your AI Connector verstuurt webhooks via een beveiligde verbinding (HTTPS). Zorg ervoor dat het webadres dat u opgeeft HTTPS gebruikt.
• Als uw systeem een fout retourneert, wordt de bezorging als mislukt beschouwd.
• Houd de uptime van uw ontvangende systeem in de gaten om te voorkomen dat u gebeurtenissen mist.
• Schakel voor kritieke workflows Mislukte bezorgingen opnieuw proberen in en overweeg ook een fallback-mechanisme.

Webhooks worden automatisch uitgeschakeld na herhaalde fouten. Als je webhook-URL herhaaldelijk faalt (ongeveer 5 fouten achter elkaar, of 3 achter elkaar voor configuratiefouten), stopt Your AI Connector automatisch met het verzenden van gebeurtenissen naar die URL. Om deze weer in te schakelen zodra je eindpunt gezond is: bewerk de webhook en sla deze op met een gewijzigde URL (elke URL-wijziging schakelt deze opnieuw in), of gebruik het opnieuw inschakelen-eindpunt via de API — opnieuw opslaan met dezelfde URL is niet voldoende. Ondersteuning kan het ook voor je opnieuw inschakelen.

Probleemoplossing #

Volgende stappen #

• GoHighLevel-integratie — gebruik webhooks om Your AI Connector te integreren met GHL.
• API-toegang — combineer webhooks met de API voor krachtige automatiseringen.
• Tags gebruiken om contacten te labelen — stel tags in die uw webhooks activeren.