Webhooks

22 min

Overview

Note

To enable this feature, contact customer support.

This topic describes how to use webhooks to send real-time event data about your campaigns from Optimizely Campaign to other applications. You can create webhooks for the following events:

Message opened (open)

Link clicked (click)

Message sent (sent)

Message bounced (bounce)

Recipent unsubscribed (unsubscribe)

Spam complaint (spamcomplaint)

Opt-in (singleoptin, confirmedoptin, doubleoptin)

Recipient added to blocklist (blocklist)

Sent message was archived (archive)

Message discarded due to blocklist entry (filteredbyblocklist)

For example, you can use the data for notifications and analyses in external systems such as CRM software. You manage webhooks using the Optimizely Campaign REST API.

Additionally, there are webhooks of the type node which are used for app connections.

Note

Make sure you adhere to all statutory regulations when sharing any data with a third-party application!

NlcG-webhooks.mdxCreating and managing webhooks

Creating webhooks

Prerequisites: You see the Optimizely Campaign REST API Website.

Open the operation Create a webhook and click Try it out.

Image: Try it out

Enter the following information in the corresponding mandatory fields:

clientId. Client ID. To see the client ID, open the Optimizely Campaign menu and select Administration > API Overview > REST API.

targetUrl. URL to which the event data is to be sent. Prerequisites:

URL must be accessible and able to receive data via HTTP POST requests from the IP address 193.169.180.1 at any time

current HTTPS version and standard port 443 for HTTPS connections

type. Type of the event data to be sent.

open. Opened mailing.

click. Clicked links.

sent. Sent mailing.

bounce. Generated hard or soft bounce.

unsubscribe. Unsubscribed from newsletters. See also: Unsubscribers.

spamcomplaint. Message marked as spam.

singleoptin. New recipient via single opt-in.

confirmedoptin. New recipient via confirmed opt-in.

doubleoptin.New recipient via double Opt-in.

blocklist. Recipient added to a blocklist.

archive. Sent message archived.

filteredbyblocklist. Message discarded due to a blocklist entry.

format. Data format in which the event data is to be sent.

Note

The following data format is currently available: JSON.

Optionally, enter the following information if you want to submit the Basic HTTP Authentication header:

basicAuthUsername. User name.

basicAuthPassword. Password.

Click Execute. If the creation was successful, you receive the HTTP response status code 201.

NlcG-webhooks.mdxRetrieving webhook information

Context: Examples for webhook information are webhook ID, target URL and event type.

Prerequisites: You see the Optimizely Campaign REST API Website.

Open the operation Get information about all webhooks and click Try it out.

In the clientId mandatory field, enter your client ID. To see the client ID, open the Optimizely Campaign menu and select Administration > API Overview > REST API.

Click Execute.

Tip

You need the webhook ID for updating, verifying, activating, deactivating and deleting the webhook.

NlcG-webhooks.mdxUpdating webhooks

Prerequisites: You see the Optimizely Campaign REST API Website.

Open the operation Update a webhook and click Try it out.

Enter the following information in the corresponding mandatory fields:

clientID. Your client ID. To see the client ID, open the Optimizely Campaign menu and select Administration > API Overview > REST API.

webhookId. Webhook ID. You can retrieve the webhook ID with the operation Get information about all webhooks.

Update the information as described in Creating webhooks.

Click Execute. If the update was successful, you receive the HTTP response status code 200.

NlcG-webhooks.mdxVerifying webhooks

Context: Verification checks that the webhook is ready to use and can send event data to the specified URL.

Prerequisites: You see the Optimizely Campaign REST API Website.

Open the operation Verify a webhook and click Try it out.

Enter the following information:

clientID. Your client ID. To see the client ID, open the Optimizely Campaign menu and select Administration > API Overview > REST API.

webhookId. Webhook ID. You can retrieve the webhook ID with the operation Get information about all webhooks.

mailinId. ID of a valid mailing, for example a test mailing in Smart Campaigns.

Click Execute. If the verification was successful, you receive the HTTP response status code 200.

NlcG-webhooks.mdxActivating webhooks

Context: To export event data in real time, you must activate the corresponding webhook.

Prerequisites: You see the Optimizely Campaign REST API Website.

Open the operation Activate a webhook and click Try it out.

Enter the following information in the corresponding mandatory fields:

clientID. Your client ID. To see the client ID, open the Optimizely Campaign menu and select Administration > API Overview > REST API.

webhookId. Webhook ID. You can retrieve the webhook ID with the operation Get information about all webhooks.

Click Execute. If the activation was successful, you receive the HTTP response status code 200.

NlcG-webhooks.mdxDeactivating webhooks

Context: If you no longer want to export event data, you must deactivate the webhook. The webhook still exists and you can reactivate it later.

Prerequisites: You see the Optimizely Campaign REST API Website.

Open the operation Dectivate a webhook and click Try it out.

Enter the following information in the corresponding mandatory fields:

clientID. Your client ID. To see the client ID, open the Optimizely Campaign menu and select Administration > API Overview > REST API.

webhookId. Webhook ID. You can retrieve the webhook ID with the operation Get information about all webhooks.

Click Execute.

NlcG-webhooks.mdxDeleting webhooks

Context: For example, if you no longer need a webhook or want to create new webhooks, but the creation limit per client is reached, you can delete webhooks.

Prerequisites: You see the Optimizely Campaign REST API Website.

Note

You can only delete deactivated webhooks. See Deactivating a webhook.

Open the operation Delete a webhook and click Try it out.

Enter the following information in the corresponding mandatory fields:

clientID. Your client ID. To see the client ID, open the Optimizely Campaign menu and select Administration > API Overview > REST API.

webhookId. Webhook ID. You can retrieve the webhook ID with the operation Get information about all webhooks.

Click Execute.

NlcG-webhooks.mdxEvent data

Overview

As soon as a mailing recipient performs an action, Optimizely Campaign sends the corresponding event data via a HTTP POST request to the target URL. The event data is sent in batches (lists) consisting of a maximum of 100 events each.

The JSON payload of a webhook contains the number of the current transmission attempt in the variable attempt.

Note

After successful data receiving, the target URL must return the HTTP response status code 200. Otherwise the export is retried every 10 seconds. If no data can be delivered three days after the event is created, the event is discarded.

The following sections show sample data for various webhooks. Some lines are marked in green because they are always included in the webhook payload, the other lines are determined by the type of webhook.

Sample data for opens

[{
{
"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",
}]

Sample data for clicks

{
"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",
}

Sample data for sent messages

{
"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,
}

Sample data for 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

The "category" parameter defines the bounce category; "softbounce" or "hardbounce". The "reason" parameter defines the bounce reason; "spam-related" or "other". The "thresholdExceeded" parameter defines whether the recipient exceeded the bounce limit.

Sample data for unsubscribes

{
"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"
}

Sample data for spam complaints

{
"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
}

Sample data for single opt-in and 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"
}

Sample data for 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"
}

Sample data for adding recipient to blocklist

{
"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"
}

Sample data for archiving

{
"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"
}

Sample data for discarding message due to blocklist entry

{
"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
}

Webhooks

Overview

NlcG-webhooks.mdx﻿Creating and managing webhooks

Creating webhooks

NlcG-webhooks.mdx﻿Retrieving webhook information

NlcG-webhooks.mdx﻿Updating webhooks

NlcG-webhooks.mdx﻿Verifying webhooks

NlcG-webhooks.mdx﻿Activating webhooks

NlcG-webhooks.mdx﻿Deactivating webhooks

NlcG-webhooks.mdx﻿Deleting webhooks

NlcG-webhooks.mdx﻿Event data

Overview

Sample data for opens

Sample data for clicks

Sample data for sent messages

Sample data for bounces

Sample data for unsubscribes

Sample data for spam complaints

Sample data for single opt-in and confirmed opt-in

Sample data for double opt-in

Sample data for adding recipient to blocklist

Sample data for archiving

Sample data for discarding message due to blocklist entry

NlcG-webhooks.mdxCreating and managing webhooks

NlcG-webhooks.mdxRetrieving webhook information

NlcG-webhooks.mdxUpdating webhooks

NlcG-webhooks.mdxVerifying webhooks

NlcG-webhooks.mdxActivating webhooks

NlcG-webhooks.mdxDeactivating webhooks

NlcG-webhooks.mdxDeleting webhooks

NlcG-webhooks.mdxEvent data