Integraties en webhooks

Stuur gesprekken, boekingen, teamverzoeken en hulpverzoeken naar Zapier, Make of je server; controleer de handtekening en bekijk de leveringen.

Integraties sturen gebeurtenissen van je bedrijf direct door naar een andere dienst: een nieuw gesprek, een boeking, het verzoek om een teamlid, een hulpverzoek. Met Zapier of Make kun je bijvoorbeeld een rij aan een spreadsheet toevoegen, een bericht naar een chat sturen of een CRM-kaart aanmaken zonder gegevens met de hand te kopiëren.

Waar vind je ze

Open in het hoofdmenu “Modules”, koppel de module “Integraties” (standaard staat die uit) en klik op de kaart op “Integraties openen”. Het tabblad “Webhooks” wordt geopend, met ernaast het tabblad “Gebeurtenissenlogboek”. Alleen Eigenaar en Beheerder kunnen de sectie openen: het adres van een ontvanger kan een privétoken bevatten. Zolang de module uitstaat, wordt er niets bezorgd en worden gebeurtenissen in die tijd later niet opnieuw verstuurd. De ontvangers blijven ingesteld en het gebeurtenissenlogboek wordt bijgehouden.

Een ontvanger toevoegen

Maak in Zapier een Zap met de trigger “Webhooks by Zapier” en de gebeurtenis “Catch Hook” en kopieer het adres dat je krijgt. Voeg in Make de module “Custom webhook” toe en kopieer het adres ervan.
Vul op de integratiepagina “Naam” (bijvoorbeeld de naam van de Zap) en “Adres van de ontvanger” (het gekopieerde adres) in.
Vink bij “Te versturen gebeurtenissen” aan wat verstuurd moet worden.
Klik op “Ontvanger toevoegen”.
Het ondertekeningsgeheim verschijnt maar één keer. Kopieer het en bewaar het veilig. Zapier en Make hebben het niet nodig; je eigen server gebruikt het om de handtekening te controleren. Ben je het kwijt, maak dan met “Geheim wijzigen” een nieuw geheim.
Klik op de kaart van de ontvanger op “Test versturen”. Het resultaat is Afgeleverd of Niet afgeleverd, met de reden.

Het adres moet openbaar zijn en met https beginnen. Geweigerd worden, met vermelding van de reden: http-adressen, IP-adressen in plaats van een domein, eigen poorten, adressen met gebruikersnaam en wachtwoord, interne adressen en adressen op ReceptionWorks-domeinen. De pagina toont alleen host en pad van het adres: het deel na het vraagteken kan het token van je ontvanger bevatten.

Welke gebeurtenissen worden verstuurd

“Nieuw gesprek” (conversation.started): een klant is in een willekeurig kanaal een nieuw gesprek begonnen. Testchats en geblokkeerde klanten worden niet verstuurd.
“Teamlid gevraagd” (conversation.handoff_requested): de AI-medewerker of het systeem heeft om een teamlid gevraagd. De gebeurtenis bevat de reden: verzoek van de AI-medewerker zelf, gestopte automatische antwoorden, handmatige modus, niet-beschikbare AI-medewerker, opgebruikte antwoordlimiet of niet-actief abonnement.
“Gesprek overgedragen aan een teamlid” (conversation.handed_off): een teamlid heeft het gesprek overgenomen. Dit wordt elke keer verstuurd.
“Nieuwe boeking”, “Boeking gewijzigd” en “Boeking geannuleerd” (booking.created, booking.changed, booking.cancelled): een boeking is gemaakt, gewijzigd of geannuleerd door een AI-medewerker, door jou in de agenda of door de bedrijfsassistent.
“Nieuw hulpverzoek” (support_case.created) en “Hulpverzoek gewijzigd” (support_case.updated): een hulpverzoek is aangemaakt, of de status, prioriteit of beschrijving is gewijzigd. Interne notities van het team worden niet verstuurd.
„Nieuw bericht” (message.created): elk bericht dat de klant ziet, verstuurd zodra het is geschreven: van de klant, de AI-medewerker, een teamlid of het systeem (een melding in het gesprek). De berichttekst zit erbij.
„Volledig gesprek” (conversation.transcript): het hele gesprek, verstuurd wanneer er 30 minuten geen bericht is geweest. Gaat het gesprek verder, dan wordt het na elke volgende pauze opnieuw verstuurd.

Gebeurtenissen uit de testchat worden niet verstuurd. Een ontvanger krijgt alleen gebeurtenissen die plaatsvinden na het toevoegen en zolang hij aanstaat: wat tijdens een pauze of uitschakeling gebeurt, wordt later niet nagestuurd.

„Nieuw bericht” en „Volledig gesprek” bevatten de volledige tekst van gesprekken, ook wat klanten schrijven. De tekst verlaat ReceptionWorks en gaat naar de ontvanger die je koos, dus vink ze alleen aan voor ontvangers die je vertrouwt. Een nieuwe ontvanger begint met deze twee uitgevinkt. Ze worden alleen verstuurd zolang een ontvanger ze heeft aangevinkt en staan niet in het gebeurtenissenlogboek of de export ervan: het gesprek zelf staat in de inbox. Testchats en geblokkeerde klanten worden niet verstuurd.

Wat de ontvanger krijgt

Elke gebeurtenis is een POST-verzoek met een JSON-body. Voorbeeld voor een verzoek om een teamlid door een AI-medewerker:

{
  "schema_version": "business-webhook.v1",
  "id": "5b0c5e2e-0000-4000-8000-000000000001",
  "type": "conversation.handoff_requested",
  "occurred_at": "2026-10-07T09:30:00.000Z",
  "business": { "name": "Example Studio" },
  "actor": { "kind": "ai_employee" },
  "channel": "telegram",
  "employee": { "name": "Anna" },
  "conversation": { "url": "https://app.example.com/businesses/studio/inbox?conversation=example" },
  "customer": { "name": "Maria", "email": "maria@example.com", "phone": "+1 555 0100" },
  "booking": null,
  "handoff": { "reason": "ai_request", "reason_text": "The customer wants to discuss a discount" },
  "support_case": null
}

id: de id van de gebeurtenis. Die blijft bij elke nieuwe poging gelijk, dus negeer een id die je al hebt verwerkt.
type: het type gebeurtenis uit de lijst hierboven; occurred_at: de tijd in UTC.
business: de naam van je bedrijf.
actor: wie de gebeurtenis veroorzaakte. kind is customer, ai_employee, team_member (een teamlid of de bedrijfsassistent) of system.
channel: web, telegram, instagram, whatsapp of messenger, of null als de gebeurtenis geen gesprek heeft.
employee: de naam van de AI-medewerker, of null als het team of de bedrijfsassistent handelde.
conversation.url: een link naar het gesprek; die opent voor ingelogde teamleden. null als er geen gesprek is.
customer: naam, e-mail en telefoon op het moment van verzenden, of null. Contactgegevens worden volledig verstuurd, voeg dus alleen ontvangers toe die je vertrouwt.
booking: alleen bij boekingsgebeurtenissen: service, starts_at, ends_at, status en location.
handoff: alleen bij “Teamlid gevraagd”: reason (ai_request, automation_stopped, manual_mode, ai_unavailable, quota_exhausted of plan_inactive) en reason_text, de eigen uitleg van de AI-medewerker of null.
support_case: alleen bij gebeurtenissen van hulpverzoeken: subject, status (open, in_progress, waiting_customer, resolved of closed) en priority (low, normal, high of urgent).
message: alleen voor „Nieuw bericht”: id, sequence (de plaats van het bericht in het gesprek), author (customer, ai_employee, team_member of system), text, created_at en attachments: een lijst met kind (altijd image), name en media_type. Alleen de naam en het type van de bijlage worden verstuurd, niet het bestand.
transcript: alleen voor „Volledig gesprek”: message_count (berichten in het gesprek), truncated en messages: berichten in dezelfde vorm als message. Een transcript bevat maximaal de 500 meest recente berichten en 512 KiB tekst; truncated is true als oudere berichten zijn weggelaten.

Onderdelen die niet bij de gebeurtenis horen, zijn null. De gebeurtenis van “Test versturen” heeft het type webhook.test en alle onderdelen behalve business zijn null. De gegevens bevatten geen vertaalde tekst: namen zijn zoals opgeslagen, codes zijn vaste Engelse woorden en tijden zijn in UTC.

"message": {
  "id": "6c1d0f52-0000-4000-8000-000000000002",
  "sequence": 12,
  "author": "customer",
  "text": "Hello, can I book for Friday?",
  "created_at": "2026-10-07T09:29:41.000Z",
  "attachments": [{ "kind": "image", "name": "photo.jpg", "media_type": "image/jpeg" }]
}

Berichten en transcripten kunnen in de verkeerde volgorde aankomen en zich herhalen, dus reken niet op de aankomstvolgorde. Gebruik sequence om de volgorde van de berichten in een gesprek te herstellen en negeer een levering waarvan je de webhook-id al hebt verwerkt. Het transcript herhaalt berichten die je misschien al een voor een hebt ontvangen: gebruik het om het hele gesprek te controleren of opnieuw op te bouwen.

De handtekening controleren

Elk verzoek heeft drie headers van de standaard Standard Webhooks: webhook-id, webhook-timestamp en webhook-signature. Zapier en Make controleren ze niet. Gebruik op je eigen server de officiële Standard Webhooks-bibliotheek voor jouw taal: geef haar het geheim precies zoals getoond (het begint met whsec_), de ongewijzigde ruwe body van het verzoek en de drie headers. Handmatige controle:

signed_content = webhook-id + "." + webhook-timestamp + "." + raw request body
signature      = "v1," + base64( HMAC-SHA256( key, signed_content ) )
key            = base64-decoded part of the secret after "whsec_"

De header webhook-signature bevat v1, gevolgd door de handtekening. Na “Geheim wijzigen” bevat hij twee handtekeningen, gescheiden door een spatie: accepteer het verzoek als een van beide klopt. Weiger verzoeken waarvan de tijdstempel meer dan vijf minuten van je klok afwijkt.

Nieuwe pogingen en automatisch uitschakelen

De ontvanger moet binnen 10 seconden met een 2xx-code antwoorden. Doorverwijzingen worden niet gevolgd: een adres dat doorverwijst, telt als fout. Anders probeert ReceptionWorks het opnieuw: meteen, daarna na 1 minuut, 5 minuten, 30 minuten, 2 uur, 6 uur en 12 uur. Dat zijn 7 pogingen in ongeveer 21 uur. Mislukken ze allemaal, dan staat de levering in “Leveringslogboek” als Niet afgeleverd en kun je op “Opnieuw versturen” klikken. Nieuwe pogingen dragen dezelfde webhook-id, zodat de ontvanger dubbele gebeurtenissen kan negeren.

Een ontvanger wordt automatisch uitgeschakeld als hij meldt dat het adres niet meer bestaat (code 410) of als vijf gebeurtenissen achter elkaar niet worden afgeleverd. De kaart toont dan “Automatisch uitgeschakeld” met de reden en je team krijgt een melding. Herstel het adres en klik op “Inschakelen”: gemiste gebeurtenissen worden niet nagestuurd.

Pauze, nieuw geheim, verwijderen

“Pauzeren” stopt het verzenden zonder de ontvanger te verwijderen; klik op “Inschakelen” om door te gaan.
“Geheim wijzigen” en daarna “Nieuw geheim maken”: een nieuw geheim wordt één keer getoond. Het oude blijft 24 uur geldig, zodat je de ontvanger kunt bijwerken zonder gebeurtenissen te missen.
“Verwijderen” en daarna “Ontvanger verwijderen” verwijderen de ontvanger definitief.

Goed om te weten

Alleen Eigenaar en Beheerder beheren integraties. Een bedrijf kan tot 5 ontvangers hebben.
Het leveringslogboek toont gebeurtenis, ontvanger, tijd, status, pogingen en de volgende poging. De tekst van verzoeken wordt niet bewaard.
Testen met “Test versturen” maakt geen logboekregel aan en heeft geen echte gebeurtenis nodig.