Webhooks mit deinen eigenen Systemen verbinden

Mit einem Webhook sendet Beamcore automatisch eine Nachricht an eine Adresse deiner Wahl, sobald etwas passiert, zum Beispiel wenn ein Projekt angelegt wird. So hältst du ein eigenes System auf dem Laufenden, ohne selbst Daten abzutippen. Die Beamcore-Oberfläche ist auf Niederländisch, daher stehen Schaltflächen und Menüs hier auf Niederländisch mit Übersetzung.

Achtung: Das Menü Integraties (Integrationen) ist nicht standardmäßig eingeschaltet. Es ist eine Einstellung pro Unternehmen, die Beamcore auf Wunsch für dich aktiviert. Siehst du das Menü nicht, nimm Kontakt mit Beamcore auf. Außerdem ist das Menü nur für einen Inhaber des Unternehmens sichtbar.

Einen Webhook anlegen

1. Gehe zu Integraties → Webhooks (Integrationen → Webhooks) und lege einen neuen Webhook an.
2. Trage einen Naam (Name) ein, an dem du die Verbindung erkennst.
3. Trage bei URL die Adresse ein, unter der dein System die Nachrichten empfängt.
4. Hake unter Events (Ereignisse) an, worüber du eine Nachricht erhalten willst. Du musst mindestens eines wählen.
5. Lass Actief (Aktiv) eingeschaltet und speichere.

Ein Webhook, der nicht aktiv ist, erhält keine Nachrichten. Über Bewerken (Bearbeiten) passt du Name, URL und Ereignisse später an.

Die verfügbaren Ereignisse

Für diese Ereignisse verschickt Beamcore Nachrichten:

• Project aangemaakt (Projekt angelegt, project.created): Ein neues Projekt wurde angelegt. Die Nachricht enthält die ID und den Namen des Projekts.
• Project gearchiveerd (Projekt archiviert, project.archived): Ein Projekt erhält den Status archiviert. Die Nachricht enthält die ID, den Namen und den vorherigen Status.
• Tekening geüpload (Zeichnung hochgeladen, drawing.uploaded): Eine neue Zeichnung wurde einem Projekt hinzugefügt. Die Nachricht enthält die ID und den Namen der Zeichnung und die ID des Projekts.
• Test-bericht (Testnachricht, webhook.test): die Nachricht, die die Schaltfläche Stuur test (Test senden) verschickt.

So sieht eine Nachricht aus

Beamcore sendet jede Nachricht als POST-Anfrage mit einem JSON-Inhalt an deine URL. Der Inhalt hat immer drei Felder:

• event: der Name des Ereignisses, zum Beispiel project.created.
• occurred_at: der Zeitpunkt in ISO-8601-Schreibweise.
• data: die Daten, die zum Ereignis gehören.

Bei jeder Anfrage sendet Beamcore diese Header mit:

• Content-Type: application/json.
• X-Beamcore-Event: der Name des Ereignisses.
• X-Beamcore-Signature: die Signatur der Nachricht.

Dein System muss mit einem Statuscode im 200er-Bereich antworten. Jede andere Antwort zählt als fehlgeschlagen. Beamcore wartet maximal 30 Sekunden auf eine Antwort.

Die Signatur prüfen

Jeder Webhook erhält beim Anlegen automatisch einen eigenen geheimen Schlüssel. Der Header X-Beamcore-Signature enthält den Text sha256=, gefolgt vom HMAC-SHA256 des unveränderten Inhalts der Nachricht, berechnet mit diesem Schlüssel. Berechne auf deiner Seite denselben Wert über den empfangenen Inhalt und vergleiche ihn mit dem Header. Stimmen sie überein, weißt du, dass die Nachricht von Beamcore kommt und unterwegs nicht verändert wurde.

Der geheime Schlüssel ist derzeit im Portal nicht sichtbar. Willst du die Signatur prüfen, nimm Kontakt mit Beamcore auf.

Eine Testnachricht senden

1. Klicke in der Liste beim Webhook auf Stuur test und bestätige.
2. Beamcore stellt eine Testnachricht für die URL dieses Webhooks bereit.
3. Öffne Integraties → Webhook log (Integrationen → Webhook-Log), um zu sehen, ob die Nachricht angekommen ist.

Das Ereignis Test-bericht musst du dafür nicht anhaken. Erhältst du die Meldung, dass nichts bereitgestellt wurde, prüfe, ob der Webhook aktiv ist.

Fehlgeschlagene Nachrichten

Gelingt die Zustellung nicht, versucht Beamcore es erneut, bis maximal fünf Versuche pro Nachricht. Zwischen den Versuchen liegt eine zunehmende Wartezeit: 10 Sekunden, 30 Sekunden, 2 Minuten und 10 Minuten. In der Liste der Webhooks siehst du pro Webhook Laatste succes (Letzter Erfolg) und Laatste fout (Letzter Fehler).

Das Webhook-Log

Unter Integraties → Webhook log steht jeder Zustellversuch, mit den neuesten oben. Pro Versuch siehst du:

• Webhook und Event: welche Verbindung und welches Ereignis.
• Status: der Statuscode, den dein System zurückgegeben hat.
• Ok?: ob die Zustellung gelungen ist.
• Poging (Versuch): der wievielte Versuch das war.
• Duur (ms) (Dauer in ms): wie lange dein System für die Antwort gebraucht hat.
• Fout (Fehler): der Grund, wenn es fehlgeschlagen ist, zum Beispiel ein Statuscode oder eine Zeitüberschreitung.
• Tijdstip (Zeitpunkt): wann der Versuch stattfand.

Die Kacheln über der Tabelle zeigen die Gesamtzahl der Versuche und wie viele in den letzten 24 Stunden gelungen und fehlgeschlagen sind.