Consolidate API: Webhooks

Dokumentation API
1

Webhooks

Webhooks ermöglichen es Ihnen, externe Systeme in Echtzeit über bestimmte Ereignisse in Consolidate zu informieren. Anstatt die API regelmäßig nach neuen Daten abzufragen (Polling), sendet Consolidate eine automatische HTTP-POST-Anfrage an eine von Ihnen definierte URL, sobald ein Ereignis eintritt.

Dies ist ideal, um Arbeitsabläufe zu automatisieren, Daten in anderen Systemen zu synchronisieren oder benutzerdefinierte Benachrichtigungen auszulösen.

1. Webhook einrichten

Sie können Webhooks einfach über die Benutzeroberfläche konfigurieren:

  1. Navigieren Sie zu Einstellungen → Webhooks.
  2. Klicken Sie auf „Neuen Webhook erstellen“.
  3. Füllen Sie die Felder im Konfigurationsdialog aus:
  • Name: Eine aussagekräftige Bezeichnung für Ihren Webhook (z. B. „Daten an CRM senden“).
  • URL: Die öffentliche Endpunkt-URL Ihres Dienstes, die die Webhook-Daten empfangen soll.
  • Ereignisse: Wählen Sie die Ereignisse aus, bei denen dieser Webhook ausgelöst werden soll.

Nach dem Speichern können Sie die webhook Einstellungen nochmal öffnen und es wird ihnen zusätzlich ein geheimer Signaturschlüssel (whsec_...) angezeigt. Kopieren Sie an einem sicheren Ort. Er ist essenziell für die Verifizierung der eingehenden Anfragen.

2. Sicherheit: Verifizierung von Anfragen

Um sicherzustellen, dass die an Ihren Endpunkt gesendeten Anfragen tatsächlich von Consolidate stammen und nicht von Dritten manipuliert wurden, signieren wir jede Webhook-Anfrage.

Wir verwenden hierfür den offenen Standard von Standard Webhooks .

Jede Anfrage von uns enthält die folgenden HTTP-Header:

  • webhook-id: Eine eindeutige ID für jede Webhook-Nachricht.
  • webhook-timestamp: Der Unix-Zeitstempel (in Sekunden), wann die Nachricht gesendet wurde.
  • webhook-signature: Die Signatur, die Sie verifizieren müssen.

Die genaue technische Spezifikation zur Verifizierung der Signatur sowie offizielle Bibliotheken für gängige Programmiersprachen (wie JavaScript/TypeScript, Python, PHP, C# u.v.m.) finden Sie direkt auf der Webseite des Standards.

3. Payload-Struktur

Jede Webhook-Anfrage ist eine HTTP POST-Anfrage mit einem JSON-Body. Die Struktur sieht wie folgt aus:

{
  "id": "msg_1234567890abcdef"
  "type": "dataEntry.created",
  "timestamp": "2022-11-03T20:26:10.344522Z",
  "data": {
    "id": "1234567890abcdef",
    // ... je nach Ereigniss-typ optional weitere Felder
  }
}
  • id: Die ID dieser Webhook Nachricht. Diese bleibt gleich wenn die Nachricht weiderholt wird.
  • type: Die ID des ausgelösten Ereignisses (z. B. dataEntry.created).
  • timestamp: Der Zeitpunkt zu dem dieses Ereigniss ausgelöst wurde. Achtung: Dieser Zeitpunkt unterscheidet sich vom webhook-timestamp im Header, da dieser den tatsächlichen sendezeitpunkt beschreibt.
  • data: Ein Objekt, das die Nutzdaten des Ereignisses enthält. In der Regel ist dies eine Repräsentation der Ressource, die das Ereignis ausgelöst hat.

4. Zustellungsgarantie und Idempotenz

Zustellungsprinzip: At-least-once

Consolidate sendet Webhook-Ereignisse nach dem At-least-once-Prinzip (Mindestens-einmal-Zustellung). Das bedeutet, wir garantieren, dass ein Ereignis mindestens einmal an Ihren Endpunkt gesendet wird. In seltenen Fällen (z. B. bei Netzwerkproblemen oder wenn Ihr Server nicht rechtzeitig antwortet) kann es vorkommen, dass dieselbe Nachricht mehrfach zugestellt wird.

Aus diesem Grund muss Ihr Endpunkt idempotent sein. Idempotenz bedeutet, dass die mehrfache Verarbeitung derselben Nachricht zum exakt gleichen Ergebnis führt wie die einmalige Verarbeitung.

Ein gängiger Ansatz ist es, die id jeder eingehenden Webhook-Nachricht zu speichern und zu überprüfen. Bevor Sie eine Nachricht verarbeiten, prüfen Sie, ob Sie eine Nachricht mit dieser ID bereits verarbeitet haben.

Wiederholungsversuche (Retries)

Wenn Ihr Endpunkt nicht mit einem erfolgreichen HTTP-Statuscode (2xx) antwortet oder es zu einem Timeout kommt, wird Consolidate versuchen, die Nachricht erneut zu senden. Dabei verwenden wir einen exponentiellen Backoff-Algorithmus: Die Zeit zwischen den Zustellversuchen wird schrittweise länger.

Wir unternehmen bis zu 10 Wiederholungsversuche über einen längeren Zeitraum, bevor wir die Zustellung für diese spezifische Nachricht aufgeben.

5. Best Practices

  • Schnell antworten: Ihr Endpunkt sollte so schnell wie möglich mit einem 2xx HTTP-Statuscode (z. B. 200 OK) antworten, um den Empfang zu bestätigen. Andernfalls könnte unser System die Zustellung erneut versuchen.
  • Asynchrone Verarbeitung: Führen Sie langwierige oder komplexe Logik (z. B. weitere API-Aufrufe) in einer Hintergrundaufgabe oder einer Queue aus, nachdem Sie den Empfang des Webhooks bestätigt haben. Dies verhindert Timeouts.