Real-time export of event data via webhooks (Beta)

This topic describes how to manage webhooksHTTPS callback for sending event data in real time. using the REST API documentation on Episerver World to export event data in real time. As soon as a user performs an action, such as opens or clicks, you immediately receive the corresponding event data.

Using the Episerver Campaign REST API, you can create webhooks, retrieve webhook information, activate, deactivate and delete webhooks.

Creating a webhook

Prerequisite: You must set up the REST API in your client. See REST API on Episerver World.

1. Open the operation Create a webhook and click Try it out.

   

2. Enter the following information in the corresponding mandatory fields:
   • clientID. Your client ID. To see the client ID, go to start menuMain screen in Episerver Campaign, where the available options are grouped together. > Administration > API overview > SOAP API.
   • targetUrl. The URLStands for "Uniform Resource Locator". Also known as a web address such as http://world.episerver.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. The type of the event data to be sent.

     Real-time export of event data is currently possible for opens and clicks.

   • format. The data format in which the event data is to be sent.

     The following data format is currently available: JSON.

   

3. To create the webhook, click Execute. If the creation was successful, you receive the HTTP response status code 201.
4. To retrieve information of the created webhooks, execute the operation Get information about all webhooks.

   

   You can find the following information in the Response body:

   • id. Webhook ID
   • type. Type of the event data
   • status. Webhook status
   • format. Data format of the event data
   • created. Creation date of the webhook
   • modified. Modification date of the webhook

   You need the webhook ID for activating, deactivating and deleting the webhook.

   

Activating a webhook

To export event data in real time, you must activate the corresponding webhook. Do the following:

1. Open the operation Activate a webhook and click Try it out.

   

2. Enter the following information in the corresponding mandatory fields:
   • clientID. Your client ID. To see the client ID, go to start menuMain screen in Episerver Campaign, where the available options are grouped together. > Administration > API overview > SOAP API.
   • webhookId. The ID of the webhook you want to activate. You can retrieve the webhook ID with the operation Get information about all webhooks.

     

3. To activate the webhook, click Execute. If the activation was successful, you receive the HTTP response status code 200.

As soon as a mailing recipient performs an action, Episerver Campaign sends the corresponding event data via a HTTP POST request to the target URL. The event data is sent in batches consisting of a maximum of 100 events each.

Example of event data (opens) in JSON format:

{
  "type":"open",
  "recipientId":"123456789005",
  "userListId":123456789003,
  "remoteAddress":"0.0.0.0",
  "clientId":123456789001,
  "mailingId":123456789004,
  "created":1564590054000,
  "subscriptionId":1234567,
  "mailId":"3IHQ2XT8-38PY7WFQ-XKNQSY",
  "device":"desktop",
  "operatingSystem":"Windows 10",
  "browser":"Firefox 64.1"
}

Deactivating a webhook

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:

1. Open the operation Dectivate a webhook and click Try it out.

   

2. Enter the following information in the corresponding mandatory fields:
   • clientID. Your client ID. To see the client ID, go to start menuMain screen in Episerver Campaign, where the available options are grouped together. > Administration > API overview > SOAP API.
   • webhookId. The ID of the webhook you want to deactivate. You can retrieve the webhook ID with the operation Get information about all webhooks.

     

3. To deactivate the webhook, click Execute.

Deleting a webhook

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:

1. Open the operation Delete a webhook and click Try it out.

   

2. Enter the following information in the corresponding mandatory fields:
   • clientID. Your client ID. To see the client ID, go to start menuMain screen in Episerver Campaign, where the available options are grouped together. > Administration > API overview > SOAP API.
   • webhookId. The ID of the webhook you want to delete. You can retrieve the webhook ID with the operation Get information about all webhooks.

     

3. To delete the webhook, click Execute.

In this topic