Webhooks

Overview

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.

Creating and managing webhooks

Creating webhooks

Prerequisites: You see the Optimizely Campaign REST API Website.

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

   

2. 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.

     The following data format is currently available: JSON.

3. Optionally, enter the following information if you want to submit the Basic HTTP Authentication header:
   • basicAuthUsername. User name.
   • basicAuthPassword. Password.
4. Click Execute. If the creation was successful, you receive the HTTP response status code 201.

Retrieving webhook information

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

Prerequisites: You see the Optimizely Campaign REST API Website.

1. Open the operation Get information about all webhooks and click Try it out.
2. 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.
3. Click Execute.

Updating webhooks

Prerequisites: You see the Optimizely Campaign REST API Website.

1. Open the operation Update a webhook and click Try it out.
2. 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.
3. Update the information as described in Creating webhooks.
4. Click Execute. If the update was successful, you receive the HTTP response status code 200.

Verifying 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.

1. Open the operation Verify a webhook and click Try it out.
2. 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.
3. Click Execute. If the verification was successful, you receive the HTTP response status code 200.

Activating webhooks

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

Prerequisites: You see the Optimizely Campaign REST API Website.

1. Open the operation Activate a webhook and click Try it out.
2. 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.
3. Click Execute. If the activation was successful, you receive the HTTP response status code 200.

Deactivating 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.

1. Open the operation Dectivate a webhook and click Try it out.
2. 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.
3. Click Execute.

Deleting 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.

1. Open the operation Delete a webhook and click Try it out.
2. 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.
3. Click Execute.

Event 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. 

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":"john.smith@example.com" },
"mailId":"3P5W8B4-3P5W0LI-BSLXEC",
"recipientId":"john.smith@example.com",
"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":"john.smith@example.com" },
"mailId":"4P6W8B4-4P6W0LI-BSLXEC",
"recipientId":"john.smith@example.com",
"subscriptionId":1234567,
"userListId":123456789003,
"attempt":5,
"remoteAddress":"10.420.3.42",
"mailingId":123456789004,
"device":"desktop",
"operatingSystem":"Windows 10",
"browser":"Firefox 64.1",
}]

{
"type":"click",
"clientId":10180860001,
"created":1617108763000,
"mediaTypesToAddresses": { "EMAIL":"john.smith@example.com" },
"mailId":"4P6W8B4-4P6W0LI-BSLXEC",
"recipientId":"john.smith@example.com",
"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",
}

{
"type":"sent",
"clientId":10180860001,
"created":1617108575391,
"mediaTypesToAddresses": { "EMAIL":"john.smith@example.com" },
"mailId":"4P6W8B4-4P6W0LI-BSLXEC",
"recipientId":"john.smith@example.com",
"subscriptionId":10227900201,
"userListId":10180860004,
"attempt":1,
"mailingType":"campaign",
"id":"0a673110-17883138caf-178832ea49f-2690c03e51f4cc26",
"mailingId":10230355206,
"mediaType":"EMAIL",
"mailingName":"Welcome",
"created":1617108575391,
}

{
"type":"bounce",
"clientId":10180860001,
"created":1617108575391,
"mediaTypesToAddresses": { "EMAIL":"john.smith@example.com" },
"mailId":"4P6W8B4-4P6W0LI-BSLXEC",
"recipientId":"john.smith@example.com",
"subscriptionId":10227900201,
"userListId":10180860004,
"attempt":1,
"id":"0a673102-178d27b2c8c-178d2cac0e4-c7420699923845e",
"mailingId":10230355206,
"category":"softbounce",
"mediaType":"EMAIL",
"reason":"other",
"thresholdExceeded":false,
}

{
"type":"unsubscribe",
"clientId":10180860001,
"created":1617108763000,
"mediaTypesToAddresses": { "EMAIL":"john.smith@example.com" },
"mailId":"4P6W7B7-4P5W0LI-BALXEC",
"recipientId":"john.smith@example.com",
"subscriptionId":10237984200,
"userListId":10180860009,
"attempt":2,
"reason":"Unsubscribe via REST API",
"id":"0acb3115-17aa6042099-17aaa1c69bf-6efb42209c0b1",
"mailingId":10230355205,
"mediaType":"EMAIL"
}

{
"type":"spamcomplaint",
"clientId":10180860001,
"created":1617108763000,
"mediaTypesToAddresses": { "EMAIL":"john.smith@example.com" },
"mailId":"4P6W7B7-4P5W0LI-BALXEC",
"recipientId":"john.smith@example.com",
"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":"john.smith@example.com" },
"mailId":"4P6W7B7-4P5W0LI-BALXEC",
"recipientId":"john.smith@example.com",
"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":"john.smith@example.com" },
"mailId":"4P6W7B7-4P5W0LI-BALXEC",
"recipientId":"john.smith@example.com",
"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":"john.smith@example.com" },
"mailId":"4P6W7B7-4P5W0LI-BALXEC",
"recipientId":"john.smith@example.com",
"subscriptionId":10237984200,
"userListId":10180860009,
"attempt":2
"reason": "abc"
}

Sample data for archiving

{
"type":"archived",
"clientId":10180860001,
"created":1617108763000,
"mediaTypesToAddresses": { "EMAIL":"john.smith@example.com" },
"mailId":"4P6W7B7-4P5W0LI-BALXEC",
"recipientId":"john.smith@example.com",
"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":"john.smith@example.com" },
"mailId":"4P6W7B7-4P5W0LI-BALXEC",
"recipientId":"john.smith@example.com",
"subscriptionId":10237984200,
"userListId":10180860009,
"attempt":2,
mailingId: 123456
}