Working with the Optimizely Campaign webhooks

Using webhooks, you can get real-time event data on sent mailings, opens, clicks, bounces, and unsubscribes. For example, instead of retrieving the data on a regular basis by using the response data export job, our REST API based webhooks provide you with the data within seconds. 

You can immediately process the data and create, for example, in-app notifications or monitoring dashboards in third-party systems such as CRM software. So, you don´t have to open Optimizely Campaign to check which mailings were successfully delivered to the recipient.  

Early adopter: METRO.digital

METRO.digital, the company behind the digital solutions for the METRO global wholesale business, is one of the first implementers of our webhooks. METRO.digital uses the API client Postman and our Swagger documentation to test the webhooks and build new solutions for processing customer data:  

• Updating customer master data
  Keeping the customer's subscription status up to date by using the bounce and unsubscribe events. 
• Real-time monitoring and analyses
  Analyzing the mailing dispatch (uptime/downtime, queueing/delays) based on the sent event to provide a backup plan in case of delayed transactional mails. 
• Reporting and scoring
  Enriching the data warehouse with internal campaign information and analyzing the customer's channel affinity, scoring and campaign performance for detailed campaign reports. 

Creating a webhook for the bounce event

In the following example, I want to show you how to create a webhook for the bounce event using the Optimizely Campaign REST API.

A bounce occurs when a message could not be delivered. There are two types of bounces: 

• Soft bounce. Possible reason: The mailbox is full, but the recipient may receive mailings again later.
• Hard bounce. Possible reason: The email address no longer exists.

To create the webhook, use the POST/{clientId}/webhooks operation. You need the following information: 

• Client ID. The ID of the client the REST API is set up for. You can find the client ID in Optimizely Campaign under Administration > API Overview > REST API.
• Format. Data format in which the event data is to be sent. Currently available: JSON.
• Type. Event type "bounce".
• Target URL. URL to which the event data is to be sent.
  
  Note: Make sure that the URL is accessible and able to receive data via HTTP POST requests from the IP address 193.169.180.1 at any time. Use the latest HTTPS version and standard port 443 for HTTPS connections.

The request in curl looks as follows:

curl -X POST "https://api.campaign.episerver.net/rest/123456789/webhooks" 
-H "Authorization: BASIC k783r3fjn989dhnfjjdr83dgds1383NDfv="
-d "format=json&type=bounce&targetUrl=https%3A%2F%2Fwww.example.com"

After creating the webhook, you can verify the webhook whether it is ready to use and can send event data to the specified target URL by using the GET/{clientId}/webhooks/{webhookId}/verify operation. 

Activating the webhook und retrieving real-time event data

To activate the created webhook, use the POST/{clientId}/webhooks/{webhookId}/activate operation. 

Specify the client ID and the webhook ID which you get as response when creating the webhook.  

The request in curl looks as follows:

curl -X POST "https://api.campaign.episerver.net/rest/123456789/webhooks/987654321/activate" 
-H "Authorization: BASIC k783r3fjn989dhnfjjdr83dgds1383NDfv="

After activating, the event data is sent to the specified target URL whenever a bounce occurs. The payload consists of the following data, among other:

• Bounce category - "softbounce" or "hardbounce"
• Bounce reason - "spam-related" or "other"
• Media type of the bounced message, e.g., "EMAIL"
• Mailing ID
• Recipient ID 

Sample payload in JSON format:

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