Philipp Gaska
Aug 23, 2021
  1801
(1 votes)

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.  

Tip: Regularly check our Release Notes for updates. We continuously improve and extend the webhook functionalities and will provide more event types in future. 

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.
Note: To enable the webhook feature, contact customer support. See also: Webhooks in the Optimizely user guide. 

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.  

Tip: You can also use the GET/{clientId}/webhooks operation to retrieve the IDs of all created webhooks. 

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 
}
Tip: To update the webhook without deactivating it or creating a new one, for example, to change the target URL, you can use the PUT/{clientId}/webhooks/{webhookId} operation.
Aug 23, 2021

Comments

Please login to comment.
Latest blogs
Extended SelectionFactory

In one of my previous articles I described new Color Picker widget. Today I’d like to show another simple property. I prepared extended version of...

Grzegorz Wiecheć | Jun 7, 2023 | Syndicated blog

Unlock Creativity with Text Generation

Need fresh and innovative content ideas? The Epicweb.Optimizely.AIAssistant Addon has got you covered with its text generation feature. In this blo...

Luc Gosso (MVP) | Jun 6, 2023 | Syndicated blog

Breaking Language Barriers with Multilingual Text Translation

In today's globalized world, effective communication across languages is essential. The Epicweb.Optimizely.AIAssistant Addon makes language...

Luc Gosso (MVP) | Jun 6, 2023 | Syndicated blog

Optimizely Search & Navigation - Get autocomplete suggestions in right language

When you are using Optimizely Search & Navigation (Find) to help you generate autocomplete suggestions server side in a multi-language scenario it...

Allan Thraen | Jun 5, 2023 | Syndicated blog

Easy property inheritance in Optimizely CMS

Ever needed a way to inherit property values down through the page hierarchy in Optimizely CMS 12? Now there is an easy way to enable that.

Allan Thraen | Jun 5, 2023 | Syndicated blog

Content Bulk Edit

Bulk Edit is a plugin that allows to make changes to more than one Content at the same time. This can save time by simultaneously updating multiple...

Grzegorz Wiecheć | Jun 5, 2023 | Syndicated blog