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.

Webhook Flow

Sie stellen uns einen API-Endpunkt (URL) zur Verfügung, an den wir POST-Anfragen senden, wenn bestimmte Ereignisse in unserem System auftreten.
Wir senden Ihnen einen Webhook, einschließlich einer signierten Nutzlast, um die Authentizität sicherzustellen.
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.
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:

X-Signature: Die HMAC-SHA256-Signatur zur Überprüfung.
X-Delivery-Id: Eine eindeutige UUID (Version 7), die die Webhook-Anfrage identifiziert. Sie können dies für Protokollierungs- oder Duplikationszwecke verwenden.
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:

Holen Sie sich die Webhook-Nutzlast (den Inhalt der POST-Anfrage).
Holen Sie sich die Signatur aus dem X-Signature-Header.
Erstellen Sie die Signatur neu, indem Sie denselben geheimen Schlüssel verwenden, den wir bereitgestellt haben, und die Nutzlast als JSON-String.
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:

{
  "event": "event_name",  // Der Typ des Ereignisses, z. B. "NEW_SUBSCRIPTION" oder "SUBSCRIPTION_UPDATE".
  "data": {
    "email": "user@example.com",  // Die E-Mail des Benutzers, die immer bereitgestellt wird.
    "firstname": "John",          // Optional: Vorname des Benutzers
    "lastname": "Doe",            // Optional: Nachname des Benutzers
    "gender": "FEMALE",           // Optional: Geschlecht ('MALE', 'FEMALE')
    "birthday": {
      "year": 1990,               // Optional: Geburtsjahr
      "month": 5,                 // Optional: Geburtsmonat
      "day": 15                   // Optional: Geburtstag
    }
  }
}

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.

{
  "event": "NEW_SUBSCRIPTION",
  "data": {
    "email": "john.doe@example.com",
    "firstname": "John",
    "lastname": "Doe"
  }
}

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.

{
  "event": "SUBSCRIPTION_UPDATE",
  "data": {
    "email": "john.doe@example.com",
    "firstname": "John",
    "lastname": "Doe",
    "gender": "MALE",
    "birthday": {
      "year": 1990,
      "month": 5,
      "day": 15
    }
  }
}

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

Derzeit unterstützen wir keine automatischen Wiederholungen für fehlgeschlagene Webhooks, aber diese Funktion ist für zukünftige Updates geplant.

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.

Webhooks Integration EN

Webhooks offer the option of sending notifications to an external web server as soon as certain events occur on uptain.

About Webhooks

Webhooks allow you to register for events that occur in a software system and automatically receive a data transmission to your server as soon as these events occur.

Webhooks are used to receive data in real time, as opposed to querying an API (intermittently calling an API) to determine if data is available. With webhooks, you only need to express interest in an event once when you create the webhook.

When you create a webhook, you specify a URL and subscribe to events that occur at uptain. When an event occurs for which your webhook is registered, uptain sends an HTTP request with data about the event to the specified URL. If your server is set up to listen for webhook deliveries at this URL, it can respond accordingly when the request is received.

Overview

Our webhook system allows your platform to receive event-driven notifications directly from our system. When an event is triggered in our system, we send a POST request to an endpoint provided by you with the relevant event data.

To ensure security and authenticity, each webhook request contains an HMAC signature that you can verify using the shared key we provide. This guide will walk you through our solution and show you how to verify the HMAC signature and what event models you can expect.

Please note that the webhook does not send historical data (events for already subscribed users) and events for users subscribed via our newsletter popup product from uptain will only be sent after the webhook has been configured.

Webhook Flow

You provide us with an API endpoint (URL) to which we send POST requests when certain events occur in our system.
We send you a webhook, including a signed payload, to ensure authenticity.
You verify the integrity of the request using the HMAC-SHA256 signature provided in the headers. Don't worry, we share all the necessary secrets with you in advance.
You respond with a 2xx status code to confirm the successful processing of the webhook.

Hint

In addition to the endpoint, you should provide us with a list of emails that have already been added to your system. This serves to block unnecessary messages and avoid duplicates.

Webhook-Anatomy

The HTTPS protocol is used to call the provided API endpoint with the POST request type.
The content of the HTTPS request is provided in JSON format.
The request headers contain our custom header field, which always starts with X-.

Overview of the header

Each webhook request contains the following headers:

X-Signature: The HMAC-SHA256 signature for verification
X-Delivery-Id: A unique UUID (version 7) that identifies the webhook request. You can use this for logging or duplication purposes.
X-Timestamp: The UTC Unix timestamp (in seconds) of when the webhook was sent.

Example

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

We send the headers exactly as shown in the example above, with the first capital letters and the X prefix.

Signature verification

To ensure that the webhook request was sent by us and has not been manipulated, you should check the HMAC signature in the X-Signature header.

The signature is only built on the data field; please do not use the entire payload to calculate the signature.

Example:

{
  "event": "event_name",          // This is not part of the signature calculation.
  "data": {                       // Everything below is part of the signature.
    "email": "user@example.com",
    "firstname": "John",
    "lastname": "Doe",
  }
}

Verification steps:

Get the webhook payload (the content of the POST request).
Get the signature from the X-Signature header.
Recreate the signature using the same secret key we provided and the payload as a JSON string.
Compare the newly created signature with the provided signature. If they match, the request is valid.

Example (PHP 7)

<?php
// Step 1: Get the webhook payload and the signature from the headers.
$payload = file_get_contents("php://input");
$provided_signature = $_SERVER['HTTP_X_SIGNATURE'];
$secret_key = 'your_shared_secret_key';

// Step 2: Decode the payload to extract the “data” property.
$payload_array = json_decode($payload, true);

// Step 3: Extract the “data” field.
$data = $payload_array['data'];

// Step 4: Re-encode the “data” field as JSON.
$data_json = json_encode($data);

// Step 5: Re-create the HMAC signature using only the “data” field.
$calculated_signature = hash_hmac('sha256', $data_json, $secret_key);

// Step 6: Compare the signatures.
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.";
}
?>

Hint:

Make sure that the secret_key is stored securely in your system.
The hash_equals() function is used to prevent timing attacks when comparing character strings.

Webhook-Payload

The webhook payload is delivered in the body of the POST request in JSON format. The structure depends on the event type, but follows the general format below:

{
  "event": "event_name",  // The type of event, e.g. ‘NEW_SUBSCRIPTION’ or ‘SUBSCRIPTION_UPDATE’.
  "data": {
    "email": "user@example.com",  // The user's email, which is always provided.
    "firstname": "John",          // Optional: First name of the user
    "lastname": "Doe",            // Optional: Surname of the user
    "gender": "FEMALE",           // Optional: Gender ('MALE', 'FEMALE')
    "birthday": {
      "year": 1990,               // Optional: Year of birth
      "month": 5,                 // Optional: Month of birth
      "day": 15                   // Optional: Day of birth
    }
  }
}

Hint:

As only the e-mail is a guaranteed field, the remaining fields, including first name and surname, may be missing.

Event: `NEW_SUBSCRIPTION`

This event occurs when a new user registers via the uptain newsletter pop-up product.

{
  "event": "NEW_SUBSCRIPTION",
  "data": {
    "email": "john.doe@example.com",
    "firstname": "John",
    "lastname": "Doe"
  }
}

Event: `SUBSCRIPTION_UPDATE`

This event occurs when an already subscribed user has provided further personal information via uptain's newsletter pop-up product.

{
  "event": "SUBSCRIPTION_UPDATE",
  "data": {
    "email": "john.doe@example.com",
    "firstname": "John",
    "lastname": "Doe",
    "gender": "MALE",
    "birthday": {
      "year": 1990,
      "month": 5,
      "day": 15
    }
  }
}

Response to a webhook

After processing the webhook, your system should respond with an appropriate HTTP status code.

Successful processing: Return any 2xx HTTP status code to indicate that the webhook has been successfully processed. Usually this is simply 200 (OK).
Error: Return a different status code (e.g. 4xx or 5xx) to indicate an error during processing.

Hint:

Currently we do not support automatic retries for failed webhooks, but this feature is planned for future updates.

Webhooks Integration

Über Webhooks

Überblick

Webhook Flow

Hinweis

Webhook-Anatomie

Übersicht der Header

Beispiel

Signaturüberprüfung

Überprüfungsschritte:

Beispiel (PHP 7)

Hinweise:

Webhook-Nutzlast

Hinweis

Ereignis: NEW_SUBSCRIPTION

Ereignis: SUBSCRIPTION_UPDATE

Antwort auf einen Webhook

Hinweis

Webhook-Einrichtungs-Checkliste

Webhooks Integration EN

About Webhooks

Overview

Webhook Flow

Hint

Webhook-Anatomy

Overview of the header

Example

Signature verification

Verification steps:

Example (PHP 7)

Hint:

Webhook-Payload

Hint:

Event: NEW_SUBSCRIPTION

Event: SUBSCRIPTION_UPDATE

Response to a webhook

Hint:

Webhook setup checklist

Ereignis: `NEW_SUBSCRIPTION`

Ereignis: `SUBSCRIPTION_UPDATE`

Event: `NEW_SUBSCRIPTION`

Event: `SUBSCRIPTION_UPDATE`