Philipp Gaska
Optimizely
Aug 23, 2021
visibility 4158
star star star star star star
(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

error Please login to comment.
Latest blogs
From Review to Release: Publishing My First Optimizely OCP App

Building an OCP app is only half the story. This post follows Publish Child Items from its first submission to a live App Directory release: what...

Chirag Khanna | Nov 16, 2026 |

Brilliant and Ignorant: Building an Optimizely Knowledge Base for AI Agents

Claude is a brilliant developer who has never seen Optimizely. How we gave our agents the framework experience a human needs half a year to earn:...

Allan Thraen | Nov 16, 2026 |

Budgeting for Agent Platform credits in 2027

How to budget for Optimizely Agent Platform (formerly Opal) credits in 2027: what a credit buys, how to size use cases, and what to agree with...

Matthew Dunn | Nov 15, 2026 |

Integrating Siteimprove with Optimizely: From Accessibility Compliance to Content Excellence

Over the last few months, I’ve worked on several Optimizely solution designs involving accessibility, SEO, analytics, governance, and content...

Madhu | Nov 14, 2026 |

Fallback images that fit: handling broken images with a service worker

A broken image is never the right shape On a content-heavy commerce site, some images will fail. Editors delete assets that are still referenced, C...

Allyn Thomas | Nov 14, 2026

First Impressions of Optimizely Mark Desktop

What is Mark Desktop Optimizely have announced the release of the Mark Desktop App. Mark is the name for the Optimizely Agent Platform formerly kno...

Mark Stott | Nov 12, 2026