Webhooks Integration

Owned by Arthur Wienhausen
Oct 28, 2024
5 min read

Webhooks bieten eine Möglichkeit, Benachrichtigungen an einen externen Webserver zu senden, sobald bestimmte Ereignisse auf Uptain auftreten.

Über Webhooks

Webhooks ermöglichen es Ihnen, sich für Ereignisse zu registrieren, die in einem Softwaresystem stattfinden, und automatisch eine Datenübermittlung an Ihren Server zu erhalten, sobald diese Ereignisse eintreten.

Webhooks werden verwendet, um Daten in Echtzeit zu empfangen, im Gegensatz zum Abfragen einer API (intermittierendes Aufrufen einer API), um festzustellen, ob Daten verfügbar sind. Mit Webhooks müssen Sie Ihr Interesse an einem Ereignis nur einmal bekunden, wenn Sie den Webhook erstellen.

Wenn Sie einen Webhook erstellen, geben Sie eine URL an und abonnieren Ereignisse, die bei uptain stattfinden. Wenn ein Ereignis eintritt, für das Ihr Webhook registriert ist, sendet uptain eine HTTP-Anfrage mit Daten über das Ereignis an die angegebene URL. Wenn Ihr Server so eingerichtet ist, dass er an dieser URL auf Webhook-Zustellungen lauscht, kann er bei Empfang der Anfrage entsprechend reagieren.

Überblick

Unser Webhook-System ermöglicht es Ihrer Plattform, ereignisgesteuerte Benachrichtigungen direkt von unserem System zu empfangen. Wenn ein Ereignis in unserem System ausgelöst wird, senden wir eine POST-Anfrage an einen von Ihnen bereitgestellten Endpunkt mit den relevanten Ereignisdaten.

Zur Gewährleistung von Sicherheit und Authentizität enthält jede Webhook-Anfrage eine HMAC-Signatur, die Sie mithilfe des von uns bereitgestellten gemeinsamen Schlüssels überprüfen können. Diese Anleitung führt Sie durch unsere Lösung und zeigt, wie Sie die HMAC-Signatur verifizieren und welche Ereignismodelle Sie erwarten können.

Bitte beachten Sie, dass der Webhook keine historischen Daten (Ereignisse für bereits abonnierte Benutzer) sendet und Ereignisse für Benutzer, die über unser Newsletter-Popup-Produkt von uptain abonniert haben, erst nach der Konfiguration des Webhooks gesendet werden.

Frame 1 (2).png

Webhook Flow

  1. Sie stellen uns einen API-Endpunkt (URL) zur Verfügung, an den wir POST-Anfragen senden, wenn bestimmte Ereignisse in unserem System auftreten.

  2. Wir senden Ihnen einen Webhook, einschließlich einer signierten Nutzlast, um die Authentizität sicherzustellen.

  3. Sie überprüfen die Integrität der Anfrage anhand der HMAC-SHA256-Signatur, die in den Headern bereitgestellt wird. Keine Sorge, wir teilen alle erforderlichen Geheimnisse im Voraus mit Ihnen.

  4. Sie antworten mit einem 2xx-Statuscode, um die erfolgreiche Verarbeitung des Webhooks zu bestätigen.

Hinweis

Zusätzlich zum Endpunkt sollten Sie uns eine Liste der E-Mails bereitstellen, die bereits in Ihrem System hinzugefügt wurden. Dies dient dazu, unnötige Nachrichten zu blockieren und Duplikate zu vermeiden.

Webhook-Anatomie

 

  • Das HTTPS-Protokoll wird verwendet, um den bereitgestellten API-Endpunkt mit dem POST-Anfragetyp aufzurufen.

  • Der Inhalt der HTTPS-Anfrage wird im JSON-Format bereitgestellt.

  • Die Header der Anfrage enthalten unser benutzerdefiniertes Header-Feld, das immer mit X- beginnt.

Übersicht der Header

Jede Webhook-Anfrage enthält die folgenden Header:

  1. X-Signature: Die HMAC-SHA256-Signatur zur Überprüfung.

  2. X-Delivery-Id: Eine eindeutige UUID (Version 7), die die Webhook-Anfrage identifiziert. Sie können dies für Protokollierungs- oder Duplikationszwecke verwenden.

  3. X-Timestamp: Der UTC-Unix-Zeitstempel (in Sekunden), wann der Webhook gesendet wurde.

Beispiel

X-Signature: 7be22db82868eb7b4600db8b33d54d1d3d1007b706cfc04fe2c6c6a5d85cc73a X-Delivery-Id: 01917ae1-be8f-7d07-a95d-b006a7000892 X-Timestamp: 1693093607 Content-Type: application/json

Wir senden die Header genau so, wie im obigen Beispiel gezeigt, mit den ersten Großbuchstaben und dem X-Präfix.

Signaturüberprüfung

Um sicherzustellen, dass die Webhook-Anfrage von uns gesendet wurde und nicht manipuliert wurde, sollten Sie die HMAC-Signatur im X-Signature-Header überprüfen.

Die Signatur wird nur auf das Datenfeld aufgebaut; bitte verwenden Sie nicht die gesamte Nutzlast zur Berechnung der Signatur.

Beispiel:

{ "event": "event_name", // Dies ist nicht Teil der Signaturberechnung. "data": { // Alles, was unten steht, ist Teil der Signatur. "email": "user@example.com", "firstname": "John", "lastname": "Doe", } }

Überprüfungsschritte:

  1. Holen Sie sich die Webhook-Nutzlast (den Inhalt der POST-Anfrage).

  2. Holen Sie sich die Signatur aus dem X-Signature-Header.

  3. Erstellen Sie die Signatur neu, indem Sie denselben geheimen Schlüssel verwenden, den wir bereitgestellt haben, und die Nutzlast als JSON-String.

  4. Vergleichen Sie die neu erstellte Signatur mit der bereitgestellten Signatur. Wenn sie übereinstimmen, ist die Anfrage gültig.

Beispiel (PHP 7)

<?php // Schritt 1: Holen Sie sich die Webhook-Nutzlast und die Signatur aus den Headern. $payload = file_get_contents("php://input"); $provided_signature = $_SERVER['HTTP_X_SIGNATURE']; $secret_key = 'your_shared_secret_key'; // Schritt 2: Dekodieren Sie die Nutzlast, um die 'data'-Eigenschaft zu extrahieren. $payload_array = json_decode($payload, true); // Schritt 3: Extrahieren Sie das 'data'-Feld. $data = $payload_array['data']; // Schritt 4: Kodieren Sie das 'data'-Feld erneut als JSON. $data_json = json_encode($data); // Schritt 5: Erstellen Sie die HMAC-Signatur neu, indem Sie nur das 'data'-Feld verwenden. $calculated_signature = hash_hmac('sha256', $data_json, $secret_key); // Schritt 6: Vergleichen Sie die Signaturen. if (hash_equals($calculated_signature, $provided_signature)) { // Signature is valid http_response_code(200); // Respond with 2xx status code echo "Webhook processed successfully."; } else { // Invalid signature, reject the request http_response_code(403); echo "Invalid signature."; } ?>

Hinweise:

  • Stellen Sie sicher, dass der secret_key sicher in Ihrem System gespeichert ist.

  • Die Funktion hash_equals() wird verwendet, um Timing-Angriffe beim Vergleichen von Zeichenfolgen zu verhindern.

Webhook-Nutzlast

Die Webhook-Nutzlast wird im Körper der POST-Anfrage im JSON-Format geliefert. Die Struktur hängt vom Ereignistyp ab, folgt jedoch dem allgemeinen Format unten:

Hinweis

Da nur die E-Mail ein garantiertes Feld ist, können die restlichen Felder, einschließlich Vorname und Nachname, fehlen.

Ereignis: NEW_SUBSCRIPTION

Dieses Ereignis tritt auf, wenn sich ein neuer Benutzer über das Newsletter-Popup-Produkt von uptain anmeldet.

Ereignis: SUBSCRIPTION_UPDATE

Dieses Ereignis tritt auf, wenn ein bereits abonnierter Benutzer über das Newsletter-Popup-Produkt von uptain weitere persönliche Informationen bereitgestellt hat.

Antwort auf einen Webhook

Nach der Verarbeitung des Webhooks sollte Ihr System mit einem geeigneten HTTP-Statuscode antworten.

  • Erfolgreiche Verarbeitung: Geben Sie einen beliebigen 2xx HTTP-Statuscode zurück, um anzuzeigen, dass der Webhook erfolgreich verarbeitet wurde. In der Regel ist dies einfach 200 (OK).

  • Fehler: Geben Sie einen anderen Statuscode zurück (z. B. 4xx oder 5xx), um auf einen Fehler bei der Verarbeitung hinzuweisen.

Hinweis

 

Webhook-Einrichtungs-Checkliste

Teilen Sie eine Webhook-URL mit uptain.
Erhalten Sie ein Webhook-Secret von uptain.
Implementieren Sie die HMAC-Überprüfung.
Testen Sie den Webhook mit einer echten Anmeldung.