Webhooks
Met webhooks laat Lumicast je eigen server weten wanneer er iets gebeurt in je werkomgeving: een scherm wordt toegevoegd of gewijzigd, een afspeellijst of campagne wordt gepubliceerd, enzovoort. Je server ontvangt een HTTP-POST met een JSON-payload en kan daar naar eigen inzicht op reageren.
Een webhook aanmaken
- Ga naar Werkomgeving → Webhooks (alleen voor beheerders van de werkomgeving).
- Klik op Webhook aanmaken.
- Vul in:
- Naam: iets waaraan je de webhook herkent
- Secret (optioneel): hiermee wordt elke payload ondertekend, zodat je kunt controleren dat die echt van Lumicast komt
- URL: het endpoint op je server dat de events ontvangt
- Kies onder Events op welke events deze webhook zich abonneert. Een webhook kan naar zoveel events luisteren als je wilt.
- Klik op Aanmaken.
Je kunt de URL, het secret en de abonnementen op elk moment aanpassen. Met Test webhook in de acties van een webhook stuur je een testevent en zie je het antwoord van je server.
Wat je server ontvangt
Elk event is een POST-request met een JSON-body die de wijziging beschrijft, plus deze headers:
| Header | Betekenis |
|---|---|
X-Lumicast-Event | Het eventtype, in de vorm <resource>.<action> (bijvoorbeeld DISPLAY.UPDATE) |
X-Lumicast-Resource-Type | Het soort resource waar het event over gaat |
X-Lumicast-Resource-Id | De ID van die resource |
X-Lumicast-Signature | HMAC-SHA256 van de JSON-body met je webhook-secret (alleen meegestuurd als je een secret hebt ingesteld) |
Controleer de handtekening aan jouw kant door HMAC-SHA256(secret, rawBody) als hex te berekenen en te vergelijken met de header. Komen ze niet overeen, weiger het request dan.
Aflevering en nieuwe pogingen
Lumicast verwacht dat je server binnen 5 seconden antwoordt met een 2xx-status. Mislukt het request of duurt het te lang, dan volgen nieuwe pogingen volgens dit schema: 15 s, 30 s, 1 min, 5 min, 30 min, 1 uur. Daarna wordt het event verworpen.
Zorg dat je handler idempotent is: op een traag of instabiel netwerk kan hetzelfde event meer dan eens binnenkomen.
Volledig overzicht van events
De complete lijst met eventtypes, payloadstructuren en voorbeelden staat in de API-referentie:
👉 Documentatie van webhook-events
Gebruik deze samen met de REST API-documentatie van Lumicast als je op een webhook wilt reageren door vervolgens zelf Lumicast aan te roepen.