Webhooks & API Integraties

Met webhooks kun je automatisch externe systemen op de hoogte brengen wanneer er iets gebeurt in je ticketing systeem (zoals een betaalde bestelling of nieuwe gebruiker).

Overzicht

Wat zijn Webhooks?

Webhooks zijn uitgaande HTTP POST requests die automatisch worden verstuurd naar een URL van jouw keuze wanneer bepaalde events plaatsvinden.

Voorbeeld flow:

Bezoeker koopt ticket
Betaling wordt voltooid
VoordeMensen detecteert "Order Paid" event
Webhook wordt verstuurd naar jouw URL
Jouw systeem ontvangt data en verwerkt deze

Waarom Webhooks Gebruiken?

Use cases:

CRM synchronisatie - Klantdata automatisch naar je CRM (Salesforce, HubSpot, etc.)
Marketing automation - Trigger campagnes in je marketing tool
Analytics - Verstuur data naar je analytics platform
Custom systemen - Integreer met interne systemen
Notificaties - Stuur berichten naar Slack, Discord, etc.
Accounting - Synchroniseer verkoopcijfers met je boekhoudsoftware

Webhook Types

Er zijn 2 soorten uitgaande webhooks:

1. Order Webhooks

Worden verstuurd wanneer een bestelling is betaald.

Trigger:

Order payment status = "paid"

Payload bevat:

Order gegevens (order_id, totaalbedrag, datum, etc.)
User gegevens (naam, email, telefoon, etc.)
Seats gegevens (alle tickets met event info, prijzen, kortingen)

2. User Webhooks

Worden verstuurd wanneer gebruikersgegevens wijzigen.

Triggers:

Nieuwe gebruiker aangemaakt
Gebruiker wijzigt profiel
Gebruiker schrijft zich uit (opt-out)

Payload bevat:

User gegevens (user_id, naam, email, tags, etc.)
User preferences (opt-in, mailinglist status)
Event IDs (alle events waar user tickets voor heeft)

Webhook Configureren

Stap 1: Ga naar Connections/Webhooks

Navigeer in het dashboard naar Koppelingen > Webhooks.

Stap 2: Nieuwe Webhook Toevoegen

Klik op + Nieuwe Webhook.

Stap 3: Configuratie

Veld	Uitleg
Type	Kies: `webhook`
Event	Kies: `order` of `user`
Connector URL	Het volledige HTTPS endpoint waar de webhook naartoe moet
Parameters	De JSON payload (zie Payload sectie)
Headers	Custom HTTP headers (optioneel, JSON format)

Voorbeeld configuratie:

Type: webhook
Event: order
Connector URL: https://jouwdomein.nl/api/webhooks/order
Parameters: (zie Payload Templates)
Headers: {"Authorization": "Bearer jouw_api_key"}

Payload Templates

Order Webhook Payload

Basis template:

{
  "order_id": "%ORDER_ID%",
  "user_id": "%USER_ID%",
  "firstname": "%FIRSTNAME%",
  "lastname": "%LASTNAME%",
  "email": "%EMAIL%",
  "phone": "%PHONE%",
  "payment_status": "%PAYMENT_STATUS%",
  "date": "%DATE%",
  "total_price": "%TOTAL_PRICE%",
  "optin": "%OPTIN%",
  "mailinglist": "%MAILINGLIST%"
}

Uitgebreide template met volledige objecten:

{
  "order": %ORDER%,
  "user": %USER%,
  "seats": %SEATS%,
  "event_ids": "%EVENT_IDS%"
}

User Webhook Payload

Basis template:

{
  "user_id": "%USER_ID%",
  "firstname": "%FIRSTNAME%",
  "preposition": "%PREPOSITION%",
  "lastname": "%LASTNAME%",
  "email": "%EMAIL%",
  "phone": "%PHONE%",
  "optin": "%OPTIN%",
  "mailinglist": "%MAILINGLIST%",
  "event_ids": "%EVENT_IDS%"
}

Uitgebreide template:

{
  "user": %USER%,
  "event_ids": "%EVENT_IDS%"
}

Placeholder Variabelen

Gebruik placeholders in je payload om automatisch data in te vullen.

Order Variabelen

Placeholder	Betekenis	Voorbeeld
`%ORDER_ID%`	Order ID	`1234`
`%TOTAL_PRICE%`	Totaalprijs	`47.50`
`%PAYMENT_STATUS%`	Betaalstatus	`paid`
`%DATE%`	Besteldatum	`2025-12-21 14:30:00`
`%TICKETS_NR%`	Aantal tickets	`3`
`%DONATION%`	Donatie bedrag	`5.00`
`%DISCOUNT_PRICE%`	Totale korting	`10.00`
`%FEE%`	Transactiekosten	`1.50`
`%PLACE%`	Verkoopkanaal	`www` of `pos`

User Variabelen

Placeholder	Betekenis	Voorbeeld
`%USER_ID%`	User ID	`187`
`%FIRSTNAME%`	Voornaam	`Jan`
`%PREPOSITION%`	Tussenvoegsel	`van`
`%LASTNAME%`	Achternaam	`Dijk`
`%EMAIL%`	E-mailadres	`jan@example.com`
`%PHONE%`	Telefoonnummer	`+31612345678`
`%ADDRESS%`	Adres	`Straatnaam 123`
`%ZIP%`	Postcode	`1234AB`
`%CITY%`	Stad	`Amsterdam`
`%OPTIN%`	Email opt-in	`true` of `false`
`%MAILINGLIST%`	Nieuwsbrief	`true` of `false`

Complete Objecten

Deze placeholders worden vervangen door complete JSON objecten:

Placeholder	Bevat	Gebruik
`%ORDER%`	Volledig order object	Alle order velden in JSON
`%USER%`	Volledig user object	Alle user velden in JSON
`%SEATS%`	Array van seats	Alle tickets met event info
`%EVENT_IDS%`	Comma-separated event IDs	`1113,1114,1115`

Voorbeeld %ORDER% output:

{
  "order_id": 731,
  "order_user_id": 187,
  "order_tickets_nr": 2,
  "order_total_price": "29.50",
  "order_donation": "0.00",
  "order_date": "2020-08-06 10:48:19",
  "order_payment_status": "paid",
  "order_payment_id": "tr_Hdasqzr9kb",
  "order_place": "www"
}

Voorbeeld %SEATS% output:

[
  {
    "seat_id": 281210,
    "seat_price": "23.50",
    "seat_discount": "0.00",
    "discount_name": "Standaard entreeticket",
    "event_id": 1113,
    "event_name": "De Notenkraker",
    "event_date": "2024-06-27",
    "event_time": "21:00:00",
    "event_main_id": 1082
  },
  {
    "seat_id": 281211,
    "seat_price": "0.00",
    "seat_discount": "23.50",
    "discount_name": "Vrijkaart",
    "event_id": 1113,
    "event_name": "De Notenkraker",
    "event_date": "2024-06-27",
    "event_time": "21:00:00",
    "event_main_id": 1082
  }
]

Custom Headers

Je kunt custom HTTP headers toevoegen aan je webhook requests.

Gebruik:

Authenticatie (API keys, Bearer tokens)
Custom identificatie
Content negotiation

Format: Headers worden gedefinieerd als JSON object in het connect_headers veld.

Voorbeeld:

{
  "Authorization": "Bearer sk_live_abc123xyz",
  "X-Custom-Header": "mijn-waarde",
  "X-Client-ID": "voordemensen_client"
}

Standaard headers: Elk webhook request bevat automatisch:

Content-Type: application/json
User-Agent: VoordeMensen/1.0 (Webhook System)

Webhook Testen

Voordat je een webhook live zet, kun je deze testen met dummy data.

Test Functie Gebruiken

Ga naar je webhook configuratie
Klik op Test Webhook
Het systeem verstuurt een test request met voorbeelddata
Check de response om te zien of het werkt

Test data bevat:

Order ID: 731
User ID: 187
Naam: Test VoordeMensen
Email: test@test.nl
Telefoon: `+31612345678
Alle placeholders worden gevuld met realistische test waarden

Response:

Bij succes: Je ontvangt de response van je endpoint
Bij fout: Error message met details (bijv. "URL ongeldig")

Webhook Security

HTTPS Verplicht

Alleen HTTPS endpoints worden ondersteund:

✅ https://jouwdomein.nl/webhook
❌ http://jouwdomein.nl/webhook (onveilig)

Waarom?

Beschermt gevoelige klantdata
Voorkomt man-in-the-middle attacks
Industry best practice

Debugging & Troubleshooting

Webhook Komt Niet Aan

Check:

Is de webhook actief gezet?
Is de Connector URL correct (inclusief https://)?
Is je endpoint bereikbaar vanaf het internet?
Check firewall settings (VoordeMensen IPs allowed?)
Check SSL certificate van je endpoint (geldig?)

Test:

Gebruik de test functie in het dashboard
Check je server logs voor incoming requests
Gebruik tools zoals RequestBin of Webhook.site voor debugging

Payload Komt Leeg Aan

Check:

Zijn placeholders correct gespeld? (hoofdlettergevoelig)
Zijn haakjes correct voor objecten (%ORDER% niet "%ORDER%")
Is de JSON valide? (gebruik JSON validator)

Test:

Gebruik test functie en check de verzonden payload
Log de raw body in je endpoint

Veelgestelde Vragen

Kan ik meerdere webhooks configureren?

Ja, je kunt meerdere webhooks aanmaken voor hetzelfde event type. Elk wordt apart verstuurd.

Worden webhooks gestuurd voor gratis bestellingen?

Ja, order webhooks worden verstuurd voor alle betaalde orders, inclusief €0,00 orders (vrijkaarten).

Kan ik webhooks filteren op event type?

Nee, webhooks worden verstuurd voor alle orders/users. Implementeer filtering in je endpoint op basis van de payload data.

Worden webhooks verstuurd bij refunds?

Nee, er is geen apart refund webhook. Monitor order status changes via je endpoint of gebruik de API om refund status op te halen.

Kan ik webhooks testen zonder live orders?

Ja, gebruik de test functie in het dashboard. Deze verstuurt een webhook met dummy data.

Hoe vaak worden gefaalde webhooks opnieuw geprobeerd?

Niet automatisch. Je moet handmatig opnieuw versturen via de manual trigger functie.

Kunnen webhooks naar localhost?

Nee, alleen publieke HTTPS endpoints zijn bereikbaar. Gebruik tunneling tools (ngrok, localtunnel) voor local development.

Kan ik webhooks pauzeren?

Ja, deactiveer de webhook in de configuratie. Je kunt deze later weer activeren.

Wat zijn Webhooks?​

Waarom Webhooks Gebruiken?​

Webhook Types​

1. Order Webhooks​

2. User Webhooks​

Webhook Configureren​

Stap 1: Ga naar Connections/Webhooks​

Stap 2: Nieuwe Webhook Toevoegen​

Stap 3: Configuratie​

Payload Templates​

Order Webhook Payload​

User Webhook Payload​

Placeholder Variabelen​

Order Variabelen​

User Variabelen​

Complete Objecten​

Custom Headers​

Webhook Testen​

Test Functie Gebruiken​

Webhook Security​

HTTPS Verplicht​

Debugging & Troubleshooting​

Webhook Komt Niet Aan​

Payload Komt Leeg Aan​

Veelgestelde Vragen​

Kan ik meerdere webhooks configureren?​

Worden webhooks gestuurd voor gratis bestellingen?​

Kan ik webhooks filteren op event type?​

Worden webhooks verstuurd bij refunds?​

Kan ik webhooks testen zonder live orders?​

Hoe vaak worden gefaalde webhooks opnieuw geprobeerd?​

Kunnen webhooks naar localhost?​

Kan ik webhooks pauzeren?​