Don't miss out Virtual Happy Hour this Friday (April 26).

Try our conversational search powered by Generative AI!

Philipp Gaska
Aug 23, 2021
  2177
(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
Solving the mystery of high memory usage

Sometimes, my work is easy, the problem could be resolved with one look (when I’m lucky enough to look at where it needs to be looked, just like th...

Quan Mai | Apr 22, 2024 | Syndicated blog

Search & Navigation reporting improvements

From version 16.1.0 there are some updates on the statistics pages: Add pagination to search phrase list Allows choosing a custom date range to get...

Phong | Apr 22, 2024

Optimizely and the never-ending story of the missing globe!

I've worked with Optimizely CMS for 14 years, and there are two things I'm obsessed with: Link validation and the globe that keeps disappearing on...

Tomas Hensrud Gulla | Apr 18, 2024 | Syndicated blog

Visitor Groups Usage Report For Optimizely CMS 12

This add-on offers detailed information on how visitor groups are used and how effective they are within Optimizely CMS. Editors can monitor and...

Adnan Zameer | Apr 18, 2024 | Syndicated blog

Azure AI Language – Abstractive Summarisation in Optimizely CMS

In this article, I show how the abstraction summarisation feature provided by the Azure AI Language platform, can be used within Optimizely CMS to...

Anil Patel | Apr 18, 2024 | Syndicated blog

Fix your Search & Navigation (Find) indexing job, please

Once upon a time, a colleague asked me to look into a customer database with weird spikes in database log usage. (You might start to wonder why I a...

Quan Mai | Apr 17, 2024 | Syndicated blog