Webhooks
To enable this feature, contact customer support.
This topic describes how to use webhooks HTTP callback for sending event data in real time. to receive real-time event data about your mailings. You can create webhooks for the following events:
- sent mailings
- opens
- clicks
- bounces
- unsubscribes
- spam complaints
For example, you can use the data for notifications and analyses in external systems such as CRM Stands for "customer relationship management"; a system for managing interactions with current and future customers, including support for sales, marketing, customer service and technical services. software. You manage webhooks using the Optimizely Campaign REST API.
Creating webhooks
- Open the operation Create a webhook and click 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 Stands for "Uniform Resource Locator". Also known as a web address such as http://world.optimizely.com. 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 Hard bounces occur when an email cannot be delivered due to a permanent error (for example because the email address no longer exists). or soft bounce Soft bounces occur when emails cannot be delivered due to temporary problems. This can happen, for example, if a recipient's mailbox is full. Mailboxes that reject mailings via soft bounce may be available again at a later date..
- unsubscribe. Unsubscribed from newsletters. See also: Unsubscribers.
- spamcomplaint. Message marked as spam.
- format. Data format in which the event data is to be sent.
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.
Retrieving webhook information
To retrieve information about a webhook, such as webhook ID, target URL, and event type, do the following:
- 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.
You need the webhook ID for updating, verifying, activating, deactivating and deleting the webhook.
Updating webhooks
- 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.
Verifying webhooks
To verify that the webhook is ready to use and can send event data to the specified URL Stands for "Uniform Resource Locator". Also known as a web address such as http://world.optimizely.com., do the following:
- 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.
Activating webhooks
To export event data in real time, you must activate the corresponding webhook. Do the following:
- 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.
Event data
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.
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.
[
{
"type":"open",
"recipientId":"123456789005",
"userListId":123456789003,
"remoteAddress":"10.420.3.42",
"clientId":123456789001,
"mailingId":123456789004,
"created":1564590054000,
"subscriptionId":1234567,
"mailId":"3P5W8B4-3P5W0LI-BSLXEC",
"mediaTypesToAddresses": {
"EMAIL":"[email protected]"
},
"device":"desktop",
"operatingSystem":"Windows 10",
"browser":"Firefox 64.1"
},
{
"type":"open",
"recipientId":"123456789005",
"userListId":123456789003,
"remoteAddress":"10.420.3.42",
"clientId":123456789001,
"mailingId":123456789004,
"created":1564590054000,
"subscriptionId":1234567,
"mailId":"4P6W8B4-4P6W0LI-BSLXEC",
"mediaTypesToAddresses": {
"EMAIL":"[email protected]"
},
"device":"desktop",
"operatingSystem":"Windows 10",
"browser":"Firefox 64.1"
}
]
{
"type":"click",
"link":"https://www.optimizely.com",
"mailingId":10230355206,
"remoteAddress":"10.420.3.42",
"linkId":10180855027,
"device":"desktop",
"browser":"Safari 13.1",
"operatingSystem":"Mac 10.13",
"created":1617108763000,
"mailId":"4P6W8B4-4P6W0LI-BSLXEC",
"mediaTypesToAddresses": {
"EMAIL":"[email protected]"
},
"userListId":10180860004,
"recipientId":"[email protected]",
"subscriptionId":10227900201,
"clientId":10180860001
}
{
"mailingType":"campaign",
"type":"sent",
"id":"0a673110-17883138caf-178832ea49f-2690c03e51f4cc26",
"mailingId":10230355206,
"mediaType":"EMAIL",
"mailingName":"Welcome",
"created":1617108575391,
"mailId":"4P6W8B4-4P6W0LI-BSLXEC",
"mediaTypesToAddresses": {
"EMAIL":"[email protected]"
},
"userListId":10180860004,
"recipientId":"[email protected]",
"subscriptionId":10227900201,
"clientId":10180860001
}
{
"type":"bounce",
"id":"0a673102-178d27b2c8c-178d2cac0e4-c7420699923845e",
"recipientId":"[email protected]",
"userListId":10180860004,
"clientId":10180860001,
"created":1617108575391,
"subscriptionId":10227900201,
"mailId":"4P6W8B4-4P6W0LI-BSLXEC",
"mailingId":10230355206,
"mediaTypesToAddresses": {
"EMAIL":"[email protected]"
},
"category":"softbounce",
"mediaType":"EMAIL",
"reason":"other",
"thresholdExceeded":false
}
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.
{
"type":"unsubscribe",
"reason":"Unsubscribe via REST API",
"id":"0acb3115-17aa6042099-17aaa1c69bf-6efb42209c0b1",
"mailingId":10230355205,
"mediaTypesToAddresses": {
"EMAIL":"[email protected]"
},
"mediaType":"EMAIL",
"subscriptionId":10237984200,
"mailId":"4P6W7B7-4P5W0LI-BALXEC",
"created":1617108763000,
"recipientId":"[email protected]",
"userListId":10180860009,
"clientId":10180860001,
}
{
"mailingType": "campaign",
"providerName": "AOL",
"id": "0a0a3742-17k7f11690c-13c82b66689-63eb542f53667a61",
"mailingId": 365704742069,
"type":"spamcomplaint",
"mediaTypesToAddresses": {
"EMAIL":"[email protected]"
},
"subscriptionId":10237984200,
"mailId":"4P6W7B7-4P5W0LI-BALXEC",
"created":1617108763000,
"userListId":10180860009,
"recipientId":"[email protected]",
"clientId":10180860001,
}
Deactivating webhooks
If you no longer want to export event data, you must deactivate the webhook. The webhook still exists and you can reactivate it later. Do the following:
- 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.
Deleting webhooks
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. Do the following:
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.