Webhooks
Überblick
Note
Um diese Funktion freizuschalten, wenden Sie sich an die Kundenbetreuung.
Dieses Kapitel beschreibt, wie Sie mit Webhooks Echtzeit-Ereignisdaten zu Ihren Kampagnen erhalten. Sie können Webhooks für folgende Ereignisse erstellen:
- Öffnung einer Nachricht (open)
- Link in Nachricht angeklickt (click)
- Nachricht versendet (sent)
- Bounce (bounce)
- Abbestellung (unsubscribe)
- Spam-Beschwerde (spamcomplaint)
- Opt-In (singleoptin, confirmedoptin, doubleoptin)
- Hinzufügen eines Empfängers zu einer Sperrliste (blocklist)
- Archivierung einer versendeten Nachricht (archive)
- Verwerfen einer Nachricht aufgrund eines Sperrlisteneintrags (filteredbyblocklist)
Die Daten können Sie beispielsweise für Benachrichtigungen und Analysen in externen Systemen wie CRM-Software verwenden. Webhooks verwalten Sie mithilfe der Optimizely Campaign REST-API.
Zusätzlich gibe es Webhooks vom Typ Knoten, die für App-Verbindungen genutzt werden.
Note
Beachten Sie alle rechtlichen Vorgaben, wenn Sie Daten mit einer externen Anwendung teilen!
Erstellung und Verwaltung von Webhooks
Webhooks erstellen
Voraussetzungen: Sie sehen die Optimizely Campaign REST API Website.
- Öffnen Sie die Operation Create a webhook und klicken Sie auf Try it out.
- Geben Sie in den folgenden Pflichtfeldern die entsprechenden Informationen ein:
- clientId. Mandanten-ID. Die Mandanten-ID finden Sie in Optimizely Campaign unter Verwaltung > API-Übersicht > REST-API.
- targetUrl. URL, an die die Ereignisdaten gesendet werden sollen. Voraussetzungen:
- URL muss erreichbar sein und zu jeder Zeit Daten mittels HTTP-POST-Anfragen der IP-Adresse 193.169.180.1 empfangen können
- aktuelle HTTPS-Version und Standard-Port 443 für HTTPS-Verbindungen
- type. Art der Ereignisdaten, die gesendet werden sollen.
- open. Nachricht geöffnet.
- click. Link geklickt.
- sent. Nachricht versendet.
- bounce. Hard- oder Soft-Bounce erzeugt.
- unsubscribe. Newsletter abbestellt. Siehe auch Abbesteller.
- spamcomplaint. Nachricht als Spam markiert.
- singleoptin. Empfänger per single Opt-in angemeldet.
- confirmedoptin. Empfänger per confirmed Opt-in angemeldet.
- doubleoptin. Empfänger per double Opt-in angemeldet.
- blocklist. Empfänger zu einer Sperrliste hinzugefügt.
- archive. Versendete Nachricht archiviert.
- filteredbyblocklist. Nachricht aufgrund eines Sperrlisteneintrags verworfen.
- format. Datenformat, in dem die Ereignisdaten versendet werden sollen.
Note
Derzeit ist folgendes Datenformat verfügbar: JSON.
- Geben Sie optional folgende Informationen ein, wenn Sie den Basic-HTTP-Authentifizierungsheader übermitteln möchten:
- basicAuthUsername. Benutzername.
- basicAuthPassword. Passwort.
- Klicken Sie auf Execute. Bei erfolgreicher Erstellung erhalten Sie als API-Antwort den HTTP-Statuscode 201.
Webhook-Informationen abrufen
Kontext: Informationen über einen Webhook sind zum Beispiel Webhook ID, Ziel-URL und Eventtyp.
Voraussetzungen: Sie sehen die Optimizely Campaign REST API Website.
- Öffnen Sie die Operation Get information about all webhooks und klicken Sie auf Try it out.
- Geben Sie im Pflichtfeld clientId Ihre Mandanten-ID ein. Die Mandanten-ID finden Sie im Optimizely Campaign Menü unter Verwaltung > API-Übersicht > REST-API.
- Klicken Sie auf Execute.
Tip
Sie benötigen die Webhook-ID, um den Webhook zu aktualisieren, verifizieren, aktivieren, deaktivieren und zu löschen.
Webhooks aktualisieren
Voraussetzungen: Sie sehen die Optimizely Campaign REST API Website.
- Öffnen Sie die Operation Update a webhook und klicken Sie auf Try it out.
- Geben Sie in den folgenden Pflichtfeldern die entsprechenden Informationen ein:
- clientId. Ihre Mandanten-ID. Die Mandanten-ID finden Sie im Optimizely Campaign Menü unter Verwaltung > API-Übersicht > REST-API.
- webhookId. Webhook-ID. Die Webhook-ID können Sie mit der Operation Get information about all webhooks abfragen.
- Aktualisieren Sie die Informationen wie unter Webhooks erstellen beschrieben.
- Klicken Sie auf Execute. Wenn die Aktivierung erfolgreich war, erhalten Sie den Statuscode 200.
Webhooks verifizieren
Kontext: Die Verifizerung prüft, ob der Webhook einsatzbereit ist und Ereignisdaten an die angegebene URL senden kann.
Voraussetzungen: Sie sehen die Optimizely Campaign REST API Website.
- Öffnen Sie die Operation Verify a webhook und klicken Sie auf Try it out.
- Geben Sie folgende Informationen ein:
- clientId. Ihre Mandanten-ID. Die Mandanten-ID finden Sie im Optimizely Campaign Menü unter Verwaltung > API-Übersicht > REST-API.
- webhookId. Webhook-ID. Die Webhook-ID können Sie mit der Operation Get information about all webhooks abfragen.
- mailingId. ID eines gültigen Mailings, zum Beispiel ein Test-Mailing in Smart Campaigns.
- Klicken Sie auf Execute. Wenn die Aktivierung erfolgreich war, erhalten Sie den Statuscode 200.
Webhooks aktivieren
Kontext: Um Ereignisdaten in Echtzeit zu exportieren, müssen Sie den entsprechenden Webhook aktivieren.
Voraussetzungen: Sie sehen die Optimizely Campaign REST API Website.
- Öffnen Sie die Operation Activate a webhook und klicken Sie auf Try it out.
- Geben Sie in den folgenden Pflichtfeldern die entsprechenden Informationen ein:
- clientId. Ihre Mandanten-ID. Die Mandanten-ID finden Sie im Optimizely Campaign Menü unter Verwaltung > API-Übersicht > REST-API.
- webhookId. Webhook-ID. Die Webhook-ID können Sie mit der Operation Get information about all webhooks abfragen.
- Klicken Sie auf Execute. Wenn die Aktivierung erfolgreich war, erhalten Sie den Statuscode 200.
Webhooks deaktivieren
Kontext: Wenn Sie keine Ereignisdaten mehr exportieren möchten, müssen Sie den Webhook deaktivieren. Der Webhook existiert weiterhin und Sie können ihn später reaktivieren.
Voraussetzungen: Sie sehen die Optimizely Campaign REST API Website.
- Öffnen Sie die Operation Deactivate a webhook und klicken Sie auf Try it out.
- Geben Sie in den folgenden Pflichtfeldern die entsprechenden Informationen ein:
- clientId. Ihre Mandanten-ID. Die Mandanten-ID finden Sie im Optimizely Campaign Menü unter Verwaltung > API-Übersicht > REST-API.
- webhookId. Webhook-ID. Die Webhook-ID können Sie mit der Operation Get information about all webhooks abfragen.
- Klicken Sie auf Execute.
Webhooks löschen
Kontext: Wenn Sie beispielsweise einen Webhook nicht mehr benötigen oder neue Webhooks erstellen wollen, aber das Erstellungslimit pro Mandant erreicht ist, können Sie Webhooks löschen.
Voraussetzungen: Sie sehen die Optimizely Campaign REST API Website.
Note
Sie können nur deaktivierte Webhooks löschen. Siehe Webhook deaktivieren.
- Öffnen Sie die Operation Delete a webhook und klicken Sie auf Try it out.
- Geben Sie in den folgenden Pflichtfeldern die entsprechenden Informationen ein:
- clientId. Ihre Mandanten-ID. Die Mandanten-ID finden Sie im Optimizely Campaign Menü unter Verwaltung > API-Übersicht > REST-API.
- webhookId. Webhook-ID. Die Webhook-ID können Sie mit der Operation Get information about all webhooks abfragen.
- Klicken Sie auf Execute.
Ereignisdaten
Allgemeines
Sobald ein Empfänger eine Aktion ausführt, sendet Optimizely Campaign eine HTTP-POST-Anfrage mit den entsprechenden Ereignisdaten an die Ziel-URL. Die Ereignisdaten werden in Datenpaketen (Listen) bestehend aus jeweils maximal 100 Ereignissen versendet.
Die JSON-Payload des Webhook enthält in der Variablen attempt die Nummer des aktuellen Übermittlungsversuchs.
Note
Nach erfolgreichem Datenempfang muss die Ziel-URL den HTTP-Statuscode 200 zurückgeben. Andernfalls wird der Export alle 10 Sekunden wiederholt. Wenn nach drei Tagen ab Erstellung des Ereignisses keine Daten zugestellt werden können, wird das Ereignis verworfen.
Die folgenden Abschnitte zeigen Beispieldaten für verschiedene Webhooks. Einige Zeilen sind grün markiert, weil sie immer in der Webhook-Payload enthalten sind, die übrigen Zeilen werden durch den Typ des Webhooks bestimmt.
Beispieldaten für Öffnungen
[{
{
"type":"open",
"clientId":123456789001,
"created":1564590054000,
"mediaTypesToAddresses": { "EMAIL":"[email protected]" },
"mailId":"3P5W8B4-3P5W0LI-BSLXEC",
"recipientId":"[email protected]",
"subscriptionId":1234567,
"userListId":123456789003,
"attempt":2,
"remoteAddress":"10.420.3.42",
"mailingId":123456789004,
"device":"desktop",
"operatingSystem":"Windows 10",
"browser":"Firefox 64.1",
}, {
"type":"open",
"clientId":123456789001,
"created":1564590054000,
"mediaTypesToAddresses": { "EMAIL":"[email protected]" },
"mailId":"4P6W8B4-4P6W0LI-BSLXEC",
"recipientId":"[email protected]",
"subscriptionId":1234567,
"userListId":123456789003,
"attempt":5,
"remoteAddress":"10.420.3.42",
"mailingId":123456789004,
"device":"desktop",
"operatingSystem":"Windows 10",
"browser":"Firefox 64.1",
}]Beispieldaten für Klicks
{
"type":"click",
"clientId":10180860001,
"created":1617108763000,
"mediaTypesToAddresses": { "EMAIL":"[email protected]" },
"mailId":"4P6W8B4-4P6W0LI-BSLXEC",
"recipientId":"[email protected]",
"subscriptionId":10227900201,
"userListId":123456789003,
"attempt":5,
"link":"https://www.optimizely.com",
"mailingId":10230355206,
"remoteAddress":"10.420.3.42",
"linkId":10180855027,
"device":"desktop",
"browser":"Safari 13.1",
"operatingSystem":"Mac 10.13",
}Beispieldaten für versendete Nachrichten
{
"type":"sent",
"clientId":10180860001,
"created":1617108575391,
"mediaTypesToAddresses": { "EMAIL":"[email protected]" },
"mailId":"4P6W8B4-4P6W0LI-BSLXEC",
"recipientId":"[email protected]",
"subscriptionId":10227900201,
"userListId":10180860004,
"attempt":1,
"mailingType":"campaign",
"id":"0a673110-17883138caf-178832ea49f-2690c03e51f4cc26",
"mailingId":10230355206,
"mediaType":"EMAIL",
"mailingName":"Welcome",
"created":1617108575391,
}Beispieldaten für Bounces
{
"type":"bounce",
"clientId":10180860001,
"created":1617108575391,
"mediaTypesToAddresses": { "EMAIL":"[email protected]" },
"mailId":"4P6W8B4-4P6W0LI-BSLXEC",
"recipientId":"[email protected]",
"subscriptionId":10227900201,
"userListId":10180860004,
"attempt":1,
"id":"0a673102-178d27b2c8c-178d2cac0e4-c7420699923845e",
"mailingId":10230355206,
"category":"softbounce",
"mediaType":"EMAIL",
"reason":"other",
"thresholdExceeded":false,
}Tip
Der Parameter "category" gibt die Bounce-Kategorie an; "softbounce" oder "hardbounce". Der Parameter "reason" gibt den Bounce-Grund an; Spam ("spam-related") oder alle anderen ("other"). Der Parameter "thresholdExceeded" gibt an, ob der Empfänger das Bounce-Limit überschritten hat.
Beispieldaten für Abbestellungen
{
"type":"unsubscribe",
"clientId":10180860001,
"created":1617108763000,
"mediaTypesToAddresses": { "EMAIL":"[email protected]" },
"mailId":"4P6W7B7-4P5W0LI-BALXEC",
"recipientId":"[email protected]",
"subscriptionId":10237984200,
"userListId":10180860009,
"attempt":2,
"reason":"Unsubscribe via REST API",
"id":"0acb3115-17aa6042099-17aaa1c69bf-6efb42209c0b1",
"mailingId":10230355205,
"mediaType":"EMAIL"
}Beispieldaten für Spam-Beschwerden
{
"type":"spamcomplaint",
"clientId":10180860001,
"created":1617108763000,
"mediaTypesToAddresses": { "EMAIL":"[email protected]" },
"mailId":"4P6W7B7-4P5W0LI-BALXEC",
"recipientId":"[email protected]",
"subscriptionId":10237984200,
"userListId":10180860009,
"attempt":2,
"mailingType": "campaign",
"providerName": "AOL",
"id": "0a0a3742-17k7f11690c-13c82b66689-63eb542f53667a61",
"mailingId": 365704742069
}Beispieldaten für single Opt-In und confirmed Opt-In
{
"type":"singleoptin",
"clientId":10180860001,
"created":1617108763000,
"mediaTypesToAddresses": { "EMAIL":"[email protected]" },
"mailId":"4P6W7B7-4P5W0LI-BALXEC",
"recipientId":"[email protected]",
"subscriptionId":10237984200,
"userListId":10180860009,
"attempt":2,
optinProcessId: 123456,
id: "abcdef",
mediaType: "EMAIL"
}Beispieldaten für double Opt-In
{
"type":"doubleoptin",
"clientId":10180860001,
"created":1617108763000,
"mediaTypesToAddresses": { "EMAIL":"[email protected]" },
"mailId":"4P6W7B7-4P5W0LI-BALXEC",
"recipientId":"[email protected]",
"subscriptionId":10237984200,
"userListId":10180860009,
"attempt":2,
optinProcessId: 123456,
id: abcdef,
mediaType: EMAIL,
mailingId: 123456,
mailingType: "abcdef"
mailingName: "abcdef"
}Beispieldaten für Hinzufügen eines Empfängers zu Sperrliste
{
"type":"blocklist",
"clientId":10180860001,
"created":1617108763000,
"mediaTypesToAddresses": { "EMAIL":"[email protected]" },
"mailId":"4P6W7B7-4P5W0LI-BALXEC",
"recipientId":"[email protected]",
"subscriptionId":10237984200,
"userListId":10180860009,
"attempt":2
"reason": "abc"
}Beispieldaten für Archivierung
{
"type":"archived",
"clientId":10180860001,
"created":1617108763000,
"mediaTypesToAddresses": { "EMAIL":"[email protected]" },
"mailId":"4P6W7B7-4P5W0LI-BALXEC",
"recipientId":"[email protected]",
"subscriptionId":10237984200,
"userListId":10180860009,
"attempt":2,
"id": "123456",
"mailingId": 123456,
"mailingType": "abcdef",
"mailingName": "abcdef",
"mediaType": "EMAIL"
}Beispieldaten für Verwerfen aufgrund eines Sperrlisteneintrags
{
"type":"filteredbyblocklist",
"clientId":10180860001,
"created":1617108763000,
"mediaTypesToAddresses": { "EMAIL":"[email protected]" },
"mailId":"4P6W7B7-4P5W0LI-BALXEC",
"recipientId":"[email protected]",
"subscriptionId":10237984200,
"userListId":10180860009,
"attempt":2,
mailingId: 123456
}