Met een webhook stuurt Beamcore automatisch een bericht naar een adres van jouw keuze zodra er iets gebeurt, bijvoorbeeld als er een project wordt aangemaakt. Zo houd je een eigen systeem op de hoogte zonder zelf gegevens over te typen.
Let op: het menu Integraties staat niet standaard aan. Het is een instelling per bedrijf die Beamcore op verzoek voor je inschakelt. Zie je het menu niet, neem dan contact op met Beamcore. Daarnaast is het menu alleen zichtbaar voor een eigenaar van het bedrijf.
Een webhook aanmaken
- Ga naar Integraties → Webhooks en maak een nieuwe webhook aan.
- Vul een Naam in waaraan je de koppeling herkent.
- Vul bij URL het adres in waar je systeem de berichten ontvangt.
- Vink onder Events aan waarover je een bericht wilt krijgen. Je moet er minstens een kiezen.
- Laat Actief aan staan en sla op.
Een webhook die niet actief is, ontvangt geen berichten. Via Bewerken pas je de naam, URL en events later aan.
De beschikbare events
Voor deze events verstuurt Beamcore berichten:
- Project aangemaakt (project.created): er is een nieuw project aangemaakt. Het bericht bevat het id en de naam van het project.
- Project gearchiveerd (project.archived): een project krijgt de status gearchiveerd. Het bericht bevat het id, de naam en de vorige status.
- Tekening geüpload (drawing.uploaded): er is een nieuwe tekening aan een project toegevoegd. Het bericht bevat het id en de naam van de tekening en het id van het project.
- Test-bericht (webhook.test): het bericht dat de knop Stuur test verstuurt.
Zo ziet een bericht eruit
Beamcore stuurt elk bericht als POST-verzoek met een JSON-inhoud naar je URL. De inhoud heeft altijd drie velden:
- event: de naam van het event, bijvoorbeeld project.created.
- occurred_at: het tijdstip in ISO 8601-notatie.
- data: de gegevens die bij het event horen.
Bij elk verzoek stuurt Beamcore deze headers mee:
- Content-Type: application/json.
- X-Beamcore-Event: de naam van het event.
- X-Beamcore-Signature: de handtekening van het bericht.
Je systeem moet antwoorden met een statuscode in de 200-reeks. Elk ander antwoord telt als mislukt. Beamcore wacht maximaal 30 seconden op een antwoord.
De handtekening controleren
Elke webhook krijgt bij het aanmaken automatisch een eigen geheime sleutel. De header X-Beamcore-Signature bevat de tekst sha256=, gevolgd door de HMAC-SHA256 van de onbewerkte inhoud van het bericht, berekend met die sleutel. Bereken aan jouw kant dezelfde waarde over de ontvangen inhoud en vergelijk die met de header. Komen ze overeen, dan weet je dat het bericht van Beamcore komt en onderweg niet is aangepast.
De geheime sleutel is op dit moment niet zichtbaar in het portaal. Wil je de handtekening controleren, neem dan contact op met Beamcore.
Een testbericht sturen
- Klik in de lijst bij de webhook op Stuur test en bevestig.
- Beamcore zet een testbericht klaar voor de URL van die webhook.
- Open Integraties → Webhook log om te zien of het bericht is aangekomen.
Je hoeft het event Test-bericht hiervoor niet aan te vinken. Krijg je de melding dat er niets is klaargezet, controleer dan of de webhook actief is.
Mislukte berichten
Lukt het bezorgen niet, dan probeert Beamcore het opnieuw, tot maximaal vijf pogingen per bericht. Tussen de pogingen zit een oplopende wachttijd: 10 seconden, 30 seconden, 2 minuten en 10 minuten. In de lijst met webhooks zie je per webhook Laatste succes en Laatste fout.
Het webhook log
Onder Integraties → Webhook log staat elke bezorgpoging, met de nieuwste bovenaan. Per poging zie je:
- Webhook en Event: welke koppeling en welk event.
- Status: de statuscode die je systeem teruggaf.
- Ok?: of de bezorging is gelukt.
- Poging: de hoeveelste poging dit was.
- Duur (ms): hoe lang je systeem over het antwoord deed.
- Fout: de reden als het mislukte, bijvoorbeeld een statuscode of een time-out.
- Tijdstip: wanneer de poging plaatsvond.
De tegels boven de tabel tonen het totaal aantal pogingen en hoeveel er in de laatste 24 uur zijn gelukt en mislukt.