Event-webhooks

Met event-webhooks horen je eigen systemen meteen wat er in je account gebeurt, voor alle assistenten tegelijk. Je hoeft geen actie aan elke assistent toe te voegen. Event-webhooks horen bij Enterprise; bij andere abonnementen legt de kaart uit hoe je overstapt.

Event	Wanneer
conversation.ended	Een gesprek (telefoon, sms, WhatsApp of webchat) is afgelopen en de samenvatting en uitkomst zijn bekend.
lead.created	Een gesprek leverde een nieuwe aanvraag op. Wordt verstuurd zodra de aanvraag is bewaard, dus vaak al tijdens het gesprek, en één keer per aanvraag.
appointment.booked	Er is een afspraak gemaakt: in de ingebouwde agenda (ook als die in Google Agenda of Microsoft 365 staat) door de assistent of op de boekingspagina, of door de assistent bij Cal.com of eTermin.
appointment.rescheduled	Een afspraak is verzet: door de assistent of door de klant op de boekingspagina.
appointment.cancelled	Een afspraak is geannuleerd: door de assistent, door de klant op de boekingspagina of door je team onder Afspraken. Je krijgt dit één keer: een geannuleerde afspraak kan niet nog eens worden geannuleerd of verzet.

Testgesprekken vanuit het dashboard sturen nooit een event.

Wat geen event stuurt

• Wijzigingen buiten Yarla. Verzet of verwijder je een afspraak rechtstreeks in Google Agenda, Microsoft 365, Cal.com of eTermin, dan horen we dat niet en sturen we niets.
• Een correctie van een aanvraag later in hetzelfde gesprek, en een nieuwe status die je team kiest. Haal de aanvraag op via de API als je de laatste stand nodig hebt; conversation.ended bevat het leadId.
• Afgerond of niet verschenen bij een afspraak.

Een webhook toevoegen

Alleen een Beheerder beheert event-webhooks.

1. Open Instellingen → Koppelingen en scrol naar Event-webhooks.
2. Vul onder Een webhook toevoegen het Adres (https) van je endpoint in.
3. Vink de Events aan die je wilt. Standaard staan ze allemaal aan.
4. Kies Webhook toevoegen.

Je kunt maximaal 5 webhooks hebben. Onder Adres en events wijzig je later het adres, de naam of de events; met de schakelaar zet je een webhook uit zonder hem te verwijderen. Wijzigingen worden vanzelf bewaard.

Een webhook toevoegen of wijzigen kan alleen binnen 2 uur na het inloggen, en alleen met je eigen login: niet terwijl een reseller of onze support in je account werkt. Zie Wijzigingen waarvoor je opnieuw inlogt.

Het adres moet een volledig https://-adres op internet zijn. Lokale en interne adressen worden geweigerd.

Wat we versturen

Elk event is een POST met Content-Type: application/json:

{
  "id": "evt_01JC4Z0Q8V9T3W6Y2B5N7K1M0P",
  "type": "conversation.ended",
  "createdAt": "2026-11-05T09:14:03.000Z",
  "businessId": "01JB...",
  "data": {
    "conversationId": "voice:...",
    "channel": "voice",
    "direction": "inbound",
    "customerPhone": "+31612345678",
    "customerPhoneVerified": true,
    "customerPhoneVerifiedBy": "caller_id",
    "customerName": "Jan Jansen",
    "outcome": "appointment_booked",
    "summary": "Jan wil zijn cv-ketel dinsdagochtend laten onderhouden.",
    "durationSeconds": 184,
    "leadId": null,
    "appointmentId": "01JC...",
    "variables": {},
    "link": "https://.../inbox/voice:..."
  }
}

• lead.created bevat de aanvraag: leadId, customerName, customerPhone, address, problem, urgency, preferredTime, summary en een link.
• appointment.booked, appointment.rescheduled en appointment.cancelled bevatten de afspraak: appointmentId, serviceName, startAt, endAt, timezone, status, guestName, guestEmail, guestPhone, de eigen fields en source. De link waarmee een klant de afspraak wijzigt, zit er nooit in.
• customerPhoneVerified (bij conversation.ended en lead.created) en guestPhoneVerified (bij afspraken) zeggen of de klant dat nummer in het gesprek heeft bewezen: true of false. customerPhoneVerifiedBy en guestPhoneVerifiedBy zeggen hoe: caller_id (de klant belde vanaf dat nummer), sms_code, email_code, call_code, whatsapp of phone_change, en null als het niet bewezen is. Allebei null als er geen nummer is of als de afspraak niet in een gesprek is geboekt of gewijzigd. Zie Bevestigd of niet bevestigd.
• appointment.rescheduled bevat ook previousStartAt en previousEndAt: de tijd van vóór het verzetten. Het appointmentId blijft hetzelfde.
• Bij Cal.com en eTermin houdt die dienst de afspraak bij: appointmentId is dan null, provider is calcom of etermin en externalId is hun eigen nummer. Bij het verzetten of annuleren van een eTermin-afspraak sturen we alleen dat nummer en de nieuwe tijd mee.
• De headers X-Yarla-Event (het type), X-Yarla-Event-Id (gelijk aan id) en X-Yarla-Delivery (één per verzending) onderscheiden events en verzendingen. Opnieuw versturen houdt het event-id, zodat je een event dat je al verwerkte kunt negeren.

Erg lange tekst wordt ingekort, zodat een verzending onder 64 KB blijft.

De handtekening controleren

Elke verzending heeft een X-Yarla-Signature-header, gemaakt met het Webhookgeheim op dezelfde pagina, precies zoals bij HTTP-acties. Lees in Webhooks hoe je hem controleert.

Nieuwe pogingen, test en opnieuw versturen

• Je endpoint heeft 5 seconden om met een 2xx te antwoorden. Bij een time-out, geen verbinding, 408, 429 of een 5xx proberen we het opnieuw, tot drie pogingen in totaal, met een korte pauze ertussen. Een ander 4xx-antwoord is definitief.
• Later proberen we het niet meer. Onder Laatste verzendingen zie je elke verzending van de afgelopen 30 dagen met het resultaat, en Opnieuw versturen stuurt dezelfde inhoud nog een keer.
• Voor Opnieuw versturen bewaren we de inhoud van elke verzending 30 dagen, of korter als je gesprekken korter bewaart. Daar staan ook een telefoonnummer, naam en samenvatting in. Verwijder je een gesprek of contact, dan blijft die inhoud bij de verzending tot die termijn voorbij is. Wil je hem meteen kwijt, verwijder dan de webhook: dat wist ook al zijn verzendingen.
• Test versturen stuurt een voorbeeldevent van het eerste type waar de webhook naar luistert, gemarkeerd met "test": true, en toont meteen het resultaat.
• Test versturen en Opnieuw versturen samen kunnen tot 20 keer per uur per account.

Na een overstap naar een goedkoper abonnement

Event-webhooks horen bij Enterprise. Stap je over naar een goedkoper abonnement, of staat er een Enterprise-betaling open, dan wordt er niets verstuurd. Je webhooks blijven bewaard, inactief, onder Instellingen → Koppelingen: ze versturen weer als je opnieuw Enterprise kiest (en de factuur betaald is), en je kunt ze nog steeds verwijderen. Zie Abonnement en facturen.

Gerelateerde artikelen

• Webhooks
• Koppelingen
• HubSpot en Pipedrive
• API