Met webhooks stuur je real-time meldingen van Beamcore naar externe systemen. Denk aan een ERP-koppeling die automatisch een werkorder aanmaakt zodra een tekening is goedgekeurd, of een Slack-melding bij elke nieuwe annotatie. Webhooks maken het mogelijk om Beamcore te integreren met je bestaande software, zonder polling en zonder handmatige tussenkomst.
Wat is een webhook
Een webhook is een HTTP POST-verzoek dat Beamcore verstuurt naar een door jou opgegeven URL zodra een bepaalde gebeurtenis plaatsvindt. Het verzoek bevat een JSON-payload met details over de gebeurtenis. Jouw systeem ontvangt het verzoek, verwerkt de payload, en stuurt een HTTP 200-antwoord terug.
Webhooks werken event-gestuurd. Je hoeft niet periodiek te controleren of er iets is veranderd; Beamcore belt je op zodra het zover is. Dit maakt integraties sneller en goedkoper qua API-gebruik.
Een endpoint registreren
- Ga naar Instellingen → Integraties → Webhooks.
- Klik op Nieuw webhook-endpoint.
- Vul de URL in van je endpoint (bijvoorbeeld
https://jouwsysteem.nl/beamcore/events). - Kies de events waarvoor je een notificatie wilt ontvangen (zie hieronder).
- Sla op. Beamcore verstuurt direct een testverzoek naar het endpoint om de verbinding te verifiëren. Zorg dat je endpoint bereikbaar is en een HTTP 200 teruggeeft.
Beschikbare events
De volgende events zijn beschikbaar voor webhooks:
document.version.uploaded: Een nieuwe versie van een document is geupload.document.approved: Een document heeft de status Goedgekeurd ontvangen.annotation.created: Een nieuwe annotatie is geplaatst op een document.annotation.resolved: Een annotatie is gemarkeerd als opgelost.project.locked: Een project is vergrendeld voor productie.project.unlocked: Een project is tijdelijk ontgrendeld.project.status.changed: De projectstatus is gewijzigd.
De payload valideren
Beamcore ondertekent elke webhook-payload met een geheime sleutel. De handtekening staat in de header X-Beamcore-Signature als HMAC-SHA256-hash van de payload, gegenereerd met jouw webhook-secret.
Valideer de handtekening aan de ontvangerzijde voordat je de payload verwerkt:
- Lees de header
X-Beamcore-Signatureuit het inkomende verzoek. - Bereken de HMAC-SHA256-hash van de raw request body met jouw webhook-secret als sleutel.
- Vergelijk de berekende hash met de ontvangen handtekening. Zijn ze gelijk, dan is het verzoek authentiek.
Verwerp verzoeken zonder geldige handtekening. Dit voorkomt dat kwaadwillenden jouw webhook-endpoint misbruiken.
Opnieuw versturen bij fouten
Als je endpoint niet bereikbaar is of een non-200-statuscode teruggeeft, probeert Beamcore de webhook opnieuw te versturen. Het schema is: direct, na 1 minuut, na 5 minuten, na 30 minuten en na 2 uur. Na de vijfde mislukte poging markeert Beamcore de afleverpoging als mislukt en stuurt een e-mailnotificatie naar de beheerder van het endpoint.
Mislukte afleveringen zijn terug te vinden via Instellingen → Integraties → Webhooks → Logboek. Klik op een mislukte aflevering om de payload en de foutmelding te bekijken. Via de knop Opnieuw versturen stuur je de payload handmatig opnieuw.