Webhooks

Webhooks are user-defined HTTP callbacks. They are usually triggered by an event, such as a read message or launched welcome email series. Webhooks are a handy tool to follow up on events in real-time – when an event occurs, a request is sent to an external URL. 

There are 2 options in our CDP to implement webhooks:

  1. Configure an external URL for the account to follow up on user activities.

  2. Set up customized requests in scenarios using a special Webhook block.

Webhooks to follow up activities

This functionality allows receiving information about all the activities of your contacts in real-time. The information is delivered as scheduled to the specified URL using POST requests as explained below.

For comparison/alternative, there is Public API. It is triggered when GET requests are sent from your side. Time intervals (3 months maximum) and parameters (email, status, and others) can be specified in the requests.

Using webhooks, you receive information about any user activities when:

  • delivered
  • delivery error
  • read
  • the recipient followed the link
  • the recipient unsubscribed
  • the recipient reported spam

messages are sent in any messaging channel.

How to configure webhooks for your account

Configure the URL on the server where you want to receive notifications and POST requests in JSON format.

Indicate that URL address in system's settings. To do that:

  1. Log in to your account.

login

  1. Click the caret next to your account name.

  2. Choose Settings.

Settings menu

  1. Choose the Laboratory item in the menu on the left side.

  2. Enable the Webhooks slide button.

  3. Click the caret of the Webhooks section.

  4. Type in/paste your URL address into the Webhook address field.

  5. Click the Save button.

Enabling webhooks

Upon saving, a GET request is sent by the system to the URL address for testing. If an error is returned, then probably your server has blocked our request. The actual cause can be determined from the server error code. If the test has passed successfully, then the setting-up is complete.

After that, perform any action in your account. For example, send yourself an email message. In several minutes, a POST request is sent to the specified address with the information about the latest actions.

POST requests are sent in JSON format in case of any actions by users (sent email, opened message, click-through, or other).

If the webhook URL does not return the HTTP 200 response code then the attempt of the POST request is repeated with incremented intervals (1 minute, 2 minutes, 4 minutes, 8 minutes, and up to 1 request per hour). The following requests are postponed until the successful delivery of the first one and then they are delivered in their sequence.

List of possible parameters

Parameter Type Description
broadcastId int Broadcast ID
workflowId int Workflow ID
workflowBlockId string Workflow block ID
sourceEventKey string Source event key
sourceEventTypeKey string Source event type key
iid string Interface ID
contactId int Contact ID
email string Contact Email
activityStatus string

Activity status:

  • DELIVERED – the message was delivered.

  • UNDELIVERED – the message was undelivered (statusDescription contains the reason).

  • READ – the message was read.

  • UNSUBSCRIBED – a contact unsubscribed from the broadcasting list.

  • CLICKED – a contact clicked links in the message.

  • SPAM – a contact reported spam.

  • SUBSCRIPTION_CHANGED – a contact changed the subscription category.

messageId int Message ID
messageInstanceId int Message instance ID
messageTag string Message tag
activityDateTime string Activity date and time
statusDescription string This field is returned only in the event when the status is UNDELIVERED. It contains the reason why the message has been undelivered. This may be a recipient server response, a system response saying that message delivery was not possible, and other similar reasons.
viewMessageLink string Contains the link to the message web-version
clickEventLink string Contains the link clicked by a contact (when the status is CLICKED)
hardBounce bool

This field is returned only in case when the status is UNDELIVERED. The parameter informs that the contact is in the black list.

false – not in the black list at the moment of message delivery

true – in the black list at the moment of message delivery

statusData   Data array
subscripton   Data array
subscriptons array of strings Subscription category keys

The test example of a webhook as JSON array with all possible status options:

[
{
"iid": "ffd3e1a7-a270-4e58-94de-5ac681c5c8e7",
"contactId": 687266822,
"activityStatus": "SUBSCRIPTION_CHANGED",
"mediaType": email,
"activityDateTime": "2019-09-26T14:45:18",
"statusData": {
"subscription": {
"subscriptions": [
"SMARTPHONES",
"TABLETS",
"LAPTOPS"
]
}
}
},
{
"broadcastId": 2833914,
"iid": "76662EBB-9FD4-4A6A-B1F8-2F594DF9B7B4",
"contactId": 295953704,
"email": "test@rambler.ru",
"activityStatus": "DELIVERED",
"mediaType": email,
"messageId": 976440,
"messageInstanceId": 1344540,
"activityDateTime": "2018-03-01T13:31:52",
"viewMessageLink": "https://123.esclick.me/test"
},
{
"broadcastId": 2833915,
"hardBounce": false,
"iid": "D5AF8EFC-2E8F-4BB5-B427-77D554B30E65",
"contactId": 357885291,
"sms": "380671234567",
"activityStatus": "UNDELIVERED",
"mediaType": sms,
"activityDateTime": "2019-10-01T03:43:49",
"statusDescription": "IM_NO_MONEY"
},
{
"broadcastId": 2833914,
"hardBounce": false,
"iid": "76662EBB-9FD4-4A6A-B1F8-2F594DF9B7B4",
"contactId": 295953704,
"email": "test@rambler.ru",
"activityStatus": "UNDELIVERED",
"mediaType": email,
"messageId": 976440,
"messageInstanceId": 1344540,
"activityDateTime": "2018-03-01T13:31:58",
"statusDescription": "smtp;554 5.7.1 Spam message rejected; If this is not spam contact abuse",
"viewMessageLink": "https://123.esclick.me/test"
},
{
"workflowId": 245460,
"workflowBlockId": "e_e9e90420db06b64c157440cd60d0b73d",
"sourceEventKey": "1258810400",
"sourceEventTypeKey": "subscribeFromApi",
"iid": "0bb5e1dc-0d1b-4deb-948f-8cea4d8ef738",
"contactId": 1258810400,
"email": "test@gmail.com",
"activityStatus": "READ",
"mediaType": email,
"messageId": 1235215,
"messageInstanceId": 1622691,
"messageTag": "1522397496",
"activityDateTime": "2018-05-15T04:05:53",
"viewMessageLink": "https://123.esclick.me/test"
},
{
"workflowId": 245460,
"workflowBlockId": "e_e9e90420db06b64c157440cd60d0b73d",
"sourceEventKey": "1258810400",
"sourceEventTypeKey": "subscribeFromApi",
"iid": "92227CB7-4EEF-4168-9EA5-43F3ED3559F8",
"contactId": 1258810400,
"email": "test@gmail.com",
"activityStatus": "UNSUBSCRIBED",
"mediaType": email,
"messageId": 1166457,
"messageInstanceId": 1550164,
"messageTag": "1521722870",
"activityDateTime": "2018-05-15T09:56:40",
"viewMessageLink": "https://123.esclick.me/test"
},
{
"workflowId": 245460,
"workflowBlockId": "e_e9e90420db06b64c157440cd60d0b73d",
"sourceEventKey": "1258810400",
"sourceEventTypeKey": "subscribeFromApi",
"iid": "d08d1e15-ea92-4d5c-8dc9-6f750250a6ff",
"contactId": 1258810400,
"email": "test@gmail.com",
"activityStatus": "CLICKED",
"mediaType": email,
"messageId": 1242672,
"messageInstanceId": 1630305,
"messageTag": "1522397496",
"activityDateTime": "2018-05-15T04:45:04",
"viewMessageLink": "https://123.esclick.me/test",
"clickEventLink": "https://test.ua/promo/"
},
{
"workflowId": 245460,
"workflowBlockId": "e_e9e90420db06b64c157440cd60d0b73d",
"sourceEventKey": "1258810400",
"sourceEventTypeKey": "subscribeFromApi",
"iid": "0ae4b6a3-59ad-426e-a40b-ce8f55bd40bc",
"contactId": 1258810400,
"email": "test@mail.ru",
"activityStatus": "SPAM",
"mediaType": email,
"messageId": 1242672,
"messageInstanceId": 1630305,
"messageTag": "1522397496",
"activityDateTime": "2018-05-15T08:23:56",
"viewMessageLink": "https://123.esclick.me/test"
}
]

 

Webhooks in workflows

Webhook workflows allow working with parameters from events and from the contact’s card in our platform.

Webhook workflow

This request uploads and sends the contact’s data from our CDP to other systems and contrariwise collects data into our platform from external systems. Using this as a part of a workflow, you can:

  1. Address your own resource, which will process the request and return data for personalization (for example, a personal promo code or a token for authorization) in the message.

  2. Send data from an event or from the contact’s card (for example, order id, additional field “contact’s id in messenger” or “Birthday”) to an external resource.

Note:

Only the contact’s data (fields + additional fields) and the parameters from an event that triggered a workflow with a webhook can be sent through a webhook.

In most cases, the data transfer in webhooks is configured in JSON format, but XML and text formats are also available.

How to create a webhook in a workflow

1. From the Dashboard page, select Automation > Workflows in the top menu.

2. Click the New workflow button.

Webhook workflow

3. Open the Actions menu on the left panel.

4. Select Webhook.

Adding webhook block

5. Click the Create webhook button on the Settings panel on the right side.

Create webhook

Webhook configuration window opens. There you can see it is possible to select GET or POST request type.

How to work with GET request

Use this request type when you want to request data on an external resource using the link to use the data in a workflow and insert it inside the workflow. The data is transmitted to an URL as “name-value” pairs. In order to configure the webhook:

Configuring GET request

  1. Enter the webhook name using any symbols (required field) and description (optional field).

  2. Enter the resource’s URL through secured HTTPS protocol (if you enter HTTP the system does not save the link). Type in variables you want to return after the interrogation symbol. In this example, we transmit the email parameter’s value from an event triggering the workflow and address the EMAIL field related to the contact’s card on the resource to which we sent the GET request.

  3. If your resource reads parameters from headers, enable Pass parameters in headers slide button.

  4. Enter corresponding variables and values you want to address.

  5. Enable the Authentication slide button.

  6. Select authentication connector.

  7. If you need to configure a new one, click the New connector button to open Create connector window.

  8. In Create connector window:

a. Enter Connector name.

b. Select Authentication type from the dropdown list:

  • Basic
  • Bearer token
  • API key

Creating connector

c. Enter login and password/token/key.

d. Click the Done button to apply the new connector in the webhook automatically.

Now you can test the request. 

Click the Send test button. Click Select contact to select a suitable contact for testing webhook’s functionality. In the opened window, use the search bar to find a contact.

You can also find a contact using segment. For that, select View contacts from the selected group.

To view the contact’s card, click the ‘eye’ icon. To confirm contact selection, click the highlighted line with the contact from the list. Click Next, then Send request.

In the same window, you get the response.

Sending GET request

If the test is successful, click the Back arrow in the top left corner of the dialog window, and 

  1. Click the Done button.

Now the new webhook is available for selection in your workflow. 

New workflow

Note:

There are three fields in the Webhook block settings for identification of a contact by a parameter from an event: “Contact ID”, “Phone” and “Contact Email”. It is sufficient to enter one of those three parameters for a workflow to identify which contact’s data shall be received/transmitted in a webhook. In our example, the workflow triggers an event with an email variable. Therefore, ${email} shall be indicated in the Webhook block for the “Contact Email” field.

Now you can show the received data in a message using the expression in Velocity language. Go to Messages → Messages → Create Email or choose your template.

Insert the expression with the value of the received variable to output dynamic data into any text area.

Example: $!mathTool.toInteger($data.contacts_get_by_email.get(0).id)

where contacts_get_by_email is the name of your webhook (here it plays the role of a data source),

get(0).id is a call to a variable in the source pointing to the required parameter. In this case that is contact id.

When testing, the contact id is inserted into the message that has been found by the email from an event using the webhook.

Test example

How to work with POST requests

Let’s see the example of when it is necessary to send the data about the contact’s city to get a promo code for him/her from an external source.

Follow the steps below to configure a webhook with the POST request:

  1. In the webhook block settings, click the Create webhook button.

  2. In the webhook configuration window, enter the webhook name.

  3. Select the POST request type.

  4. Enter the URL of a resource using the secure HTTPS protocol. In this link, you can use variables calling event parameters or contact fields. In the example, we call TOWN – the standard contact field in our system.

  5. If your application reads parameters from headers, enable the Pass parameters in headers slide button.

  6. Enter corresponding variables and their values.

  7. Enable the Authentication slide button to configure authentication parameters.

  8. Select from existing connectors or create a new one.

To create a new authentication connector:

a. Select New connector from the dropdown list.

b. In the opened window, enter the new connector name.

c. Select the required authentication type from the available ones:

  • Basic

  • Bearer token

  • API key

d. Enter login and password/token/key.

e. Click the Done button.

  1. In the body of the POST request, you can send a random amount of data. For that, enable the corresponding slide button, select the format of the data to be inserted and insert it below. Available formats: JSON, XML, text.

  2. Test the webhook to check whether the settings are correct. Press the Send test button in the Settings window

Post webhook settings

The system suggests where to take the data for testing – from the contact’s card or from an event. If the webhook URL is configured to address a parameter from an event, then during testing the system suggests choosing an event from the list of those received by the system at any time, or to enter the event’s body manually.

Sending PORT request

Since in our example we indicate addressing to the contact field, then it is necessary to select a contact from the base in the account.

Sending POST request

You can choose another contact ① or view the selected one ②.

Upon pressing the Next and Send request buttons you receive the response:

POST request promo

To show the promo code in the message, enter the following expression into the text area:

$data.get('WH5').get('promocode')

where

  • WH5 is the source name (webhook name).

  • promocode is the name of the variable containing the promo code value.

Promo code example

The result of a promo code inserted in the letter:

Promo code inserted in a letter

Webhook management

Press Manage Webhook in the webhook block settings. The window containing the list of webhooks opens. There you can:

  • create a new webhook

  • edit existing webhooks

  • test webhooks

  • delete webhooks

  • view the list of deleted webhooks

Webhook management

Any Questions?
We’re always happy to help!
Request a Callback
Fill in the form, and our specialists will call you back as soon as possible.
Request a Callback
Chat Support
We’re waiting for your questions!
Send a Chat Message
Email
Contact the eSputnik support team
Send an Email