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.

De Webhooks-pagina verstuurt alleen gegevens UIT Your AI Connector. De webhooks die hier worden ingesteld werken in één richting, van Your AI Connector naar uw andere tools. Om een nieuwe lead of andere gegevens BINNEN te halen (van een websiteformulier, uw CRM of GoHighLevel), heeft u twee opties. Een Automatisering met de Webhook-trigger geeft u een webadres waar uw formulier of tool gegevens naartoe kan sturen, en de stappen daarvan kunnen vervolgens de contactpersoon aanmaken, een bericht sturen en meer. Of uw systeem maakt een API-aanroep, bijvoorbeeld de Contactpersoon aanmaken-bewerking, met behulp van uw API-sleutel; zie API-toegang en Funnels.

Webhooks zijn alleen onderdeel van bepaalde abonnementen. Als uw abonnement geen webhooks bevat, is de pagina Webhooks niet beschikbaar en worden er geen gebeurtenissen verzonden. Alles wat u eerder hebt opgeslagen, blijft in uw account staan en wordt weer verzonden zodra u een abonnement hebt dat webhooks bevat. De functies van uw abonnement staan vermeld op uw factuurpagina en uw provider kan u vertellen naar welk abonnement u kunt overstappen.

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 24 staan vermeld in The 24 Webhook Events.
6. (Optioneel) Schakel Retry failed deliveries in als je wilt dat Your AI Connector het opnieuw probeert 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 24 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 24 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 beperkt de gebeurtenissen van een webhook niet tot 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, stelt u een webhook-URL in op die tag in het tabblad Tags van de agent-editor.

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" }
}

Lees agent, niet campaign. Campagnes zijn verplaatst naar AI-agents en Broadcasts (zie Campagnes zijn verplaatst), dus uw contacten zitten bij een agent en agent vertelt u welke agent het gesprek heeft afgehandeld. Het veld campaign wordt nog steeds verzonden zodat oudere ontvangers blijven werken, maar het is meestal null; het wordt alleen ingevuld voor een contact dat nog steeds een koppeling heeft met een klassieke campagne. Ga er niet vanuit dat campaign er altijd 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 top-level blok toe. Bijvoorbeeld: Appointment Booked, Appointment Cancelled en Appointment Rescheduled voegen een appointment-blok toe (zie Appointment Booked Webhook), New Message voegt een volledig message-blok toe met de tekst (zie New Message Webhook), en Deliveries en Reads voegen een kort message-blok toe met alleen het ID en de status van het bericht (zie Deliveries and Reads Webhook).

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 24 Webhook Events #

De 24 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 stem je ontvanger af 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,
    "ad_attribution": 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 placeholder-gegevens (John Doe, een voorbeeldcampagneblok). Een echte ‘Contact aangemaakt’-gebeurtenis 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 aan een gesprek wordt toegevoegd, op elk kanaal. Het omvat beide richtingen: berichten die uw contact naar u stuurt, en berichten die uw AI-agent, uw team of een broadcast naar hen stuurt. Het is de enige webhook die de berichttekst bevat, dus dit is de webhook die u moet gebruiken als 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,
    "ad_attribution": 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",
    "media_url": null,
    "media_content_type": null
  }
}

Er is nog steeds geen campaign-blok in deze payload. Nieuw bericht verstuurt contact, agent, user en message. Het agent-blok is toegevoegd op 15 augustus 2026 en vertelt u welke agent het gesprek afhandelt; als u meer context over het contact nodig heeft, zoek dit dan op via de API met contact.id.

Sla bijlagen kort na ontvangst op. De media_url-link werkt 7 dagen na ontvangst van het bericht niet meer, op elk kanaal (WhatsApp Business API, WhatsApp Web, Instagram, Messenger, Telegram, chatwidget en de rest); het bestand zelf blijft wel behouden. Om later een nieuwe link te verkrijgen, roept u Download een bijlage van een bericht aan met contacts/{contact.id}/messages/{message.id}. De velden zijn toegevoegd op 13 september 2026.

Wanneer media_url null is, maar de body aangeeft dat er een bestand is binnengekomen. Sommige bijlagen worden op een manier opgeslagen waarvoor geen directe link bestaat, en een gedeelde Instagram-reel, -post of -storyvermelding is een link naar Instagram, geen bestand, dus die komen ook aan als null (de body benoemt wat er is gedeeld). Voor een bestand roep je Download a message’s attachment aan met de ID van het bericht om een link te krijgen.

Geïmporteerde geschiedenis activeert deze webhook niet. Wanneer een WhatsApp Web-nummer zijn eerdere gesprekken importeert, worden die oudere berichten opgeslagen zonder dat er voor elk bericht een ‘Nieuw bericht’-melding wordt verstuurd.

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,
    "ad_attribution": 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,
    "external_reference": "crm-booking-1042",
    "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 stuurt een voorbeeld appointment-blok met verzonnen waarden, zodat je de vorm kunt opbouwen voordat er een echte boeking binnenkomt.

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.

Appointment Cancelled and Rescheduled Webhooks #

Appointment Cancelled wordt geactiveerd wanneer een afspraak wordt geannuleerd, en Appointment Rescheduled wordt geactiveerd wanneer deze naar een nieuwe start- of eindtijd wordt verplaatst. Beide worden op dezelfde manier geactiveerd, ongeacht of de AI dit tijdens een gesprek heeft gedaan, jij het in de app hebt gewijzigd, het via de API binnenkwam of iemand de gebeurtenis in de gekoppelde Google Agenda heeft gewijzigd.

Gebeurtenisnamen #

appointment_cancelled en appointment_rescheduled

Payload-indeling #

De body is hetzelfde als Appointment Booked, met de afspraak zoals deze is na de wijziging. Een annulering voegt appointment.cancelation_reason toe; een verplaatsing voegt een top-level previous-blok toe met de oude tijden:

{
  "event": "appointment_rescheduled",
  "contact": { "id": "<contact-id>", "email": "jane@example.com", "phone_number": "+15551234567", "first_name": "Jane", "last_name": "Smith" },
  "campaign": null,
  "agent": { "id": "<agent-id>", "name": "Front desk" },
  "user": { "id": "<account-id>", "email": "owner@example.com" },
  "appointment": {
    "appointment_id": "<appointment-id>",
    "start_time": "2026-07-21T09:00:00.000Z",
    "end_time": "2026-07-21T09:30:00.000Z",
    "status": "Confirmed",
    "room_name": "Room 1",
    "description": "Discovery call",
    "summary": "30 min intro",
    "google_calendar_event_id": "<calendar-event-id>",
    "external_reference": "crm-booking-1042",
    "cancelation_reason": null,
    "event": { "id": "<service-id>", "event_name": "Intro Call", "slot_duration": 30 }
  },
  "previous": {
    "start_time": "2026-07-20T15:00:00.000Z",
    "end_time": "2026-07-20T15:30:00.000Z"
  }
}

Eén wijziging, één gebeurtenis. Het annuleren van een afspraak stuurt alleen Appointment Cancelled, zelfs als de tijd in dezelfde bewerking is gewijzigd. Het alleen bewerken van de titel, notities of ruimte stuurt geen van beide. Het twee keer verplaatsen van dezelfde afspraak stuurt twee Appointment Rescheduled-gebeurtenissen.

Webhook voor afgesloten chat #

Wordt geactiveerd wanneer de AI besluit dat een gesprek ten einde is (een boeking gemaakt, een lead gediskwalificeerd, enzovoort).

Gebeurtenisnaam #

chat_concluded

Payload-indeling #

De payload bevat event, de volledige contact, de agent die de chat heeft afgehandeld en het account user. Het bevat ook conversation_cost, wat dit gesprek aan credits heeft gekost, zodat een n8n- of Make-flow dit kan loggen zonder een tweede aanroep:

{
  "event": "chat_concluded",
  "contact": { "id": "abc123", "first_name": "Jane", "channel": "whatsapp" },
  "agent": { "id": "agent_1", "name": "Sales Agent" },
  "user": { "id": "user_1" },
  "conversation_cost": {
    "credits": 7.5,
    "session_id": "sess_9f2",
    "started_at": "2026-09-26T09:14:02.000Z",
    "outcome": "contained"
  }
}

• credits: credits in rekening gebracht binnen dit gesprek, terugbetalingen in mindering gebracht. Dit wordt op dezelfde manier geteld als het rapport met gesprekskosten in de API.
• outcome: contained (de AI heeft het alleen afgehandeld), handed_off (iemand van uw team heeft geantwoord na de AI, of de AI heeft een mens gewaarschuwd) of no_ai.
• conversation_cost wordt weggelaten wanneer het cijfer op dat moment niet kan worden berekend. Behandel dit als optioneel.

Webhook voor bijgewerkte contacttags #

Wordt geactiveerd wanneer een tag wordt toegepast op een contact, en die tag een webhook-URL heeft geconfigureerd op de agent waaraan het contact is toegewezen.

Gebeurtenisnaam #

contact_tags_updated

Wanneer deze wordt geactiveerd #

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

Een contactpersoon die nog steeds een koppeling heeft met een klassieke campagne van vóór de overstap naar agents is een speciaal geval: als de tags van die campagne webhook-URL’s bevatten, worden die gebruikt; 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"
    },
    "ad_attribution": null
  },
  "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 data) zijn hier gedocumenteerd voor ontwikkelaars; de Task Created, Task Updated en Task Completed gebeurtenissen zijn selecteerbaar in de standaard gebeurtenissenlijst op het webhook-formulier zoals elke andere gebeurtenis — zie Available Trigger Events en The 24 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: elke gebeurtenis, sinds 24 september 2026. Dit omvat tag-webhooks (contact_tags_updated), de drie taakgebeurtenissen, het dagelijkse overzicht, de overzichts-webhook, Nieuw Bericht, Chat Afgesloten, Contact Gepauzeerd, Contact Hervat, Contact Niet Storen, Contact Gearchiveerd, Laag Saldo, de Broadcast-gebeurtenissen, en de contact- en activiteitsgebeurtenissen: Contact Aangemaakt, Afspraak Geboekt, Mens Gewaarschuwd, Antwoorden, Gelezen, Afleveringen, Credits Uitgegeven en Credits Opgewaardeerd. Vóór die datum werden Nieuw Bericht, Chat Afgesloten, Contact Gepauzeerd, Contact Hervat, Contact Niet Storen, Contact Gearchiveerd en de overzichts-webhook één keer verzonden, ongeacht de schakelaar. Elke gebeurtenis bevat 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.