Beschikbaar, uitgaande webhooks
Webhooks
Ontvang real-time events van Boekbaar in je eigen systemen, Make-scenario's, Zapier flows of n8n workflows.
1. Wat zijn webhooks?
Webhooks zijn HTTP POST-verzoeken die Boekbaar naar jouw endpoint stuurt wanneer er iets gebeurt, bijvoorbeeld een nieuwe afspraak, klant of review. Ideaal voor automatisering zonder polling.
2. Wanneer gebruiken?
- Sync naar CRM, boekhouding of Google Sheets
- Trigger Make/Zapier/n8n flows bij business events
- Interne notificaties of data warehouse updates
- Combineer met REST API voor verrijking (webhook + GET detail)
3. Endpoint aanmaken
- Dashboard → Ontwikkelaars → Webhooks
- Klik op Nieuw endpoint
- Vul endpoint URL, events en naam in
- Bewaar het webhook secret, nodig voor signature verification
Directe link: /dashboard/developers/webhooks
Velden: endpoint URL, geselecteerde events, status (ACTIVE), versleuteld secret.
4. Webhook signing
De handtekening is HMAC SHA256 over timestamp.payload met je endpoint secret. Het header-formaat is sha256=….
// rawBody = exact request body string (unparsed)
const signedContent = `${timestamp}.${rawBody}`;
const expected = "sha256=" + hmacSha256Hex(endpointSecret, signedContent);
// Vergelijk timing-safe met header X-Boekbaar-Signature
// Timestamp tolerantie: standaard 300 seconden5. Headers
| Header | Beschrijving |
|---|---|
| X-Boekbaar-Event | Event-type, bijv. appointment.created |
| X-Boekbaar-Delivery | Unieke delivery-ID voor logging en support |
| X-Boekbaar-Timestamp | Unix timestamp (seconden) voor replay-bescherming |
| X-Boekbaar-Signature | HMAC SHA256 handtekening: sha256=... |
6. Payload-voorbeeld
JSON body
{
"event": "appointment.created",
"createdAt": "2026-06-28T10:00:00.000Z",
"data": {
"id": "apt_example",
"status": "CONFIRMED",
"startsAt": "2026-06-28T10:00:00.000Z",
"customerId": "cus_example",
"serviceId": "svc_example"
}
}Het veld data bevat event-specifieke velden. Gebruik de REST API voor volledige records indien nodig.
7. Events
Afspraken
| Event | Beschrijving | Aanbevolen scope |
|---|---|---|
| appointment.created | Wordt verstuurd wanneer een nieuwe afspraak wordt aangemaakt. | appointments:read |
| appointment.updated | Wordt verstuurd wanneer een afspraak wordt gewijzigd. | appointments:read |
| appointment.cancelled | Wordt verstuurd wanneer een afspraak wordt geannuleerd. | appointments:read |
| appointment.completed | Wordt verstuurd wanneer een afspraak als afgerond wordt gemarkeerd. | appointments:read |
Klanten
| Event | Beschrijving | Aanbevolen scope |
|---|---|---|
| customer.created | Wordt verstuurd wanneer een nieuwe klant wordt aangemaakt. | customers:read |
| customer.updated | Wordt verstuurd wanneer klantgegevens worden gewijzigd. | customers:read |
| customer.deleted | Toekomstig event bij klantverwijdering/anonymisatie. Nog geen automatische dispatch. | customers:read |
Reviews
| Event | Beschrijving | Aanbevolen scope |
|---|---|---|
| review.received | Wordt verstuurd wanneer een nieuwe review binnenkomt. | reviews:read |
| review.updated | Wordt verstuurd wanneer reviewvelden (zoals ownerResponse) worden bijgewerkt. | reviews:read |
| review.published | Wordt verstuurd wanneer een review wordt gepubliceerd. | reviews:read |
| review.hidden | Wordt verstuurd wanneer een review wordt verborgen. | reviews:read |
Voordelen
| Event | Beschrijving | Aanbevolen scope |
|---|---|---|
| benefit.used | Toekomstig event wanneer een klantvoordeel automatisch wordt ingewisseld. Nog geen automatische dispatch. | benefits:read |
Pakketten
| Event | Beschrijving | Aanbevolen scope |
|---|---|---|
| package.assigned | Toekomstig event wanneer een pakket aan een klant wordt toegewezen. Nog geen automatische dispatch. | packages:read |
| package.redeemed | Toekomstig event wanneer pakketcredits worden ingewisseld. Nog geen automatische dispatch. | packages:read |
Loyalty
| Event | Beschrijving | Aanbevolen scope |
|---|---|---|
| loyalty.challenge_completed | Toekomstig event wanneer een klant een challenge voltooit. Nog geen automatische dispatch. | customers:read |
| loyalty.badge_earned | Toekomstig event wanneer een badge wordt verdiend. | customers:read |
| loyalty.reward_available | Geaggregeerd signaal dat klanten een beloning kunnen inwisselen. | customers:read |
| loyalty.vip_reached | Toekomstig event bij VIP level-up. | customers:read |
| loyalty.season_started | Seizoenscampagne-kans, ondernemer keurt handmatig goed. | customers:read |
| loyalty.campaign_ready | Nieuwe AI campagne-suggestie beschikbaar in dashboard. | customers:read |
Abonnement
| Event | Beschrijving | Aanbevolen scope |
|---|---|---|
| subscription.updated | Toekomstig event wanneer het abonnement wijzigt. Nog geen automatische dispatch. | subscription:read |
| subscription.cancelled | Toekomstig event wanneer het abonnement wordt opgezegd. Nog geen automatische dispatch. | subscription:read |
Branding
| Event | Beschrijving | Aanbevolen scope |
|---|---|---|
| branding.updated | Wordt verstuurd wanneer branding-instellingen wijzigen. | organization:read |
Widgets
| Event | Beschrijving | Aanbevolen scope |
|---|---|---|
| widget.clicked | Toekomstig event wanneer een embed-widget wordt geklikt. Nog geen automatische dispatch. | widgets:read |
Trust
| Event | Beschrijving | Aanbevolen scope |
|---|---|---|
| trust.updated | Wordt verstuurd wanneer het trust-profiel wijzigt. | trust:read |
Developer
| Event | Beschrijving | Aanbevolen scope |
|---|---|---|
| developer.test | Testevent om je webhook-endpoint te verifiëren. | — |
8. Retry-gedrag
Leveringen worden in de queue geplaatst. Bij falen (geen HTTP 2xx binnen 10 seconden) probeert Boekbaar opnieuw volgens onderstaand schema, maximaal 5 pogingen per delivery.
| Poging | Wachttijd |
|---|---|
| 1 | 1 minuut |
| 2 | 5 minuten |
| 3 | 15 minuten |
| 4 | 1 uur |
| 5 | 24 uur |
9. Testen
- Verstuur testevent
developer.testvanuit het webhook-dashboard - Bekijk leveringslogs onder Ontwikkelaars → Logs
- Retry mislukte deliveries handmatig na fix van je endpoint
10. Beveiliging
- Endpoint secrets worden versleuteld opgeslagen; roteer bij compromise.
- Verifieer altijd X-Boekbaar-Signature vóór verwerking.
- Weiger requests met timestamps ouder dan ~5 minuten.
- Log delivery IDs, geen secrets in logs.
- Gebruik dedicated endpoints per omgeving (test vs productie).
11. Make / Zapier / n8n
Make
Boekbaar webhook als trigger
- Maak een Custom Webhook-module in Make.
- Plak de URL in Boekbaar → Developers → Webhooks.
- Selecteer events (bijv. appointment.completed).
- Verwerk payload.data in volgende modules.
Geen officiële Make-app. Gebruik Custom Webhook + HTTP.
Zapier
Catch Hook + Boekbaar data
- Trigger: Webhooks by Zapier → Catch Hook.
- Kopieer URL naar Boekbaar webhook-endpoint.
- Kies customer.created of review.received.
- Optioneel: extra API-call naar Boekbaar REST API.
Geen officiële Zapier-app.
n8n
Webhook-node met signature check
- Webhook-node op POST /your-path.
- Function-node: verify HMAC met endpoint secret.
- IF-node op event type.
- HTTP Request voor vervolgacties.
Geen officiële n8n-node.
12. Problemen oplossen
401/403 of timeout op endpoint
Endpoint moet HTTPS zijn, binnen 10 seconden HTTP 2xx returnen, en bereikbaar zijn vanaf internet.
Signature verification faalt
Gebruik raw body (niet opnieuw JSON.stringify). Controleer timestamp en endpoint secret.
Geen events ontvangen
Controleer WEBHOOKS add-on, endpoint status ACTIVE, en geselecteerde event-types.
Herhaalde mislukte leveringen
Bekijk /dashboard/developers/logs; retry handmatig na fix; max 5 pogingen.