Webhooks für eine API-Anbindung konfigurieren

Webhooks ermöglichen es Blazelock, Scan-Updates direkt als HTTP-POST-Anfragen an Ihr System zu senden. Sie sind besonders nützlich für asynchrone Anbindungen, bei denen Ihre Anwendung automatisch reagieren soll, wenn ein Scan eingereicht, abgeschlossen oder fehlgeschlagen ist.

Auf dieser Seite erfahren Sie, wie Sie Webhooks im Blazelock Dashboard konfigurieren. Wenn Sie Payload-Strukturen, Header und Details zur Validierung suchen, lesen Sie in der technischen Webhook-Referenz weiter.

Warum Webhooks verwenden?

Webhooks sind nützlich, wenn Ihre Anwendung auf den Fortschritt eines Scans reagieren soll, ohne die API immer wieder nach Updates abzufragen.

Typische Vorteile sind:

Sie erhalten Scan-Updates nahezu in Echtzeit
Sie reduzieren unnötige Polling-Anfragen
Sie können Folgeprozesse automatisch nach relevanten Scan-Ereignissen starten
Sie halten Ihre eigenen Systeme mit dem aktuellen Scan-Status synchron

Wenn Sie noch entscheiden, ob Polling oder Webhooks besser zu Ihrer Anbindung passen, lesen Sie Polling vs. Webhooks.

Webhooks konfigurieren

Verwenden Sie den Bereich Webhook in Ihrer API-Anbindung, um die Konfiguration zu aktivieren oder zu aktualisieren.

Öffnen Sie die Detailseite der API-Anbindung und wechseln Sie zum Bereich Webhook.

Stellen Sie den Webhook-Status auf Aktiviert.

Geben Sie die URL Ihres Endpunkts ein.

Verwenden Sie eine öffentliche HTTPS-URL, die POST-Anfragen von Blazelock empfangen kann. Localhost-Endpunkte sind nicht zulässig.

Wählen Sie die Ereignisse aus, die Ihr Endpunkt erhalten soll.

Speichern Sie die Änderungen.

Webhook-Konfiguration mit Status, Endpunkt-URL und Ereignisauswahl

Sie können die Webhook-URL und die ausgewählten Ereignisse jederzeit aktualisieren.

Wenn Sie Webhooks deaktivieren und die API-Anbindung speichern, stoppt Blazelock die Zustellung von Webhooks für diese API-Anbindung sofort.

Verfügbare Ereignisse

Im Dashboard können Sie diese Scan-Ereignisse abonnieren:

file_scan.submitted: Wird ausgelöst, wenn ein neuer File-Scan über die API eingereicht wird
file_scan.completed: Wird ausgelöst, wenn ein File-Scan abgeschlossen ist und das Ergebnis vorliegt
file_scan.failed: Wird ausgelöst, wenn ein File-Scan wegen eines Fehlers nicht abgeschlossen werden konnte

Nutzen Sie die API-Referenz, wenn Sie das vollständige Ereignis-Schema, Beispiel-Payloads und die Header-Definitionen benötigen.

Webhook-Secret finden und verwalten

Sobald Webhooks aktiviert sind, zeigt das Dashboard für die API-Anbindung einen Bereich Webhook-Secret an.

Verwenden Sie dieses Secret, um den Header X-Blazelock-Webhook-Signature zu validieren, der jeder Zustellung beiliegt. Wir empfehlen ausdrücklich, die Signaturprüfung zu implementieren, bevor Sie Webhook-Payloads verarbeiten. Der vollständige Ablauf ist unter Signaturvalidierung beschrieben.

Im Dashboard können Sie:

Das aktuelle Secret anzeigen
Das Secret für Ihre serverseitige Konfiguration kopieren
Das Secret neu generieren, wenn Sie es ersetzen möchten

Wenn Sie das Webhook-Secret neu generieren, gilt die Änderung sofort. Ab diesem Moment werden alle neuen Webhook-Zustellungen mit dem neuen Secret signiert und das bisherige Secret ist sofort ungültig.

Webhook-Secret mit Anzeigen-, Kopier- und Neu-generieren-Aktion

Weiterführende technische Dokumentation

Nutzen Sie die API-Referenz für die technischen Details hinter den Einstellungen im Dashboard:

Über Webhooks für das Zustellmodell, Retry-Versuche und das allgemeine Verhalten von Webhooks
Signaturvalidierung für die sichere Prüfung signierter Anfragen
Polling vs. Webhooks für die Wahl des passenden Musters zum Abrufen von Ergebnissen
Webhook-Ereignisse für Schemas und Beispiel-Payloads