Webhooks for Tracking Activity

Webhooks allow you to track contact activity in the Reteno in real time and automatically send notifications about each event to a specified client URL

Webhooks are configured by adding an external URL to your account. After that, you will automatically receive data about contact actions across various media channels via POST requests.

The system sends requests to your server whenever one of the following events occurs:

Delivered — the message was delivered to the contact.
Undelivered — the message could not be delivered.
Read — the contact opened the message.
Unsubscribed — the contact unsubscribed from the campaign.
Clicked — the contact clicked on a link in the message.
Spam — the message was marked as spam.
Subscription changed — the contact changed their subscription category.

📘
Note
Before setting up webhooks, you need to configure an URL on your server where you want to receive messages — POST requests in JSON format — and process the data accordingly.

Creating Data Export

Open the Data export tab in your account settings, click the New data export button, and select Webhook.

Connection

Add a Webhook name and specify the Webhook URL you previously set up on your server.

Authentication (optional)

If authentication is enabled on your server, enter the login and password that your server requires to accept requests. Enable the Authentication toggle and fill in the corresponding fields.

Headers

Webhook headers allow you to pass additional information along with the request. They help quickly identify where the data came from, what it is used for, verify security, and more. This simplifies working with integrations and makes the integrations more reliable.

Click + Add header.

📘
Maximum number — 5.

Enter Key and Value.

All specified headers will be automatically added to webhook requests.

Export Activity Statuses

By default, all activity statuses are selected for tracking. You can modify this list by deselecting the checkboxes following to the statuses you don't want to track.

After setting up the data export via webhook, click the Save button.

The webhook will be active, and data will be sent in real-time to the specified URL.

Settings Verification

The system will check the URL's availability using the GET request. If errors occur, your server may block our request for various reasons. You can determine the exact cause based on the server error code on your side.

If the check is successful, the setup is complete.

After that, perform any action in your Reteno account — for example, send yourself an email. The POST request in JSON format with information about the latest activity will be sent to the specified URL.

For example, if a contact receives an email, opens it, and clicks a link, the system will sequentially send three requests with the statuses: DELIVERED, READ, and CLICKED.

Deactivating / Deleting Webhooks

To deactivate or delete the webhook, click the three-dot icon, select the desired option, and confirm the action.

📘
Note
Deactivation suspends the sending of requests, but the webhook remains saved in the system and can be reactivated later.

Data Export Editing

To change the settings, click on the webhook name, edit the data, and save the settings.

List of Possible Parameters

Parameter	Type	Description
activityDateTime	string	Activity date and time.
activityStatus	string	Activity status: `SENT`– the message is sent (for Mobile Push only) `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` – а contact clicked a link. Generated for each click on every link in the message. `SPAM` – a contact reported spam. `SUBSCRIPTION_CHANGED` – a contact changed the subscription category.
broadcastId	int	Broadcast ID.
clickEventLink	string	Contains the link clicked by a contact (when the status is `CLICKED`).
contactId	int	Contact ID.
email	string	Contact Email.
externalCustomerId	string	A unique customer ID in the client’s system.
from	string	Sender name (in Email and SMS messages).
hardBounce	bool	Returned only for the `UNDELIVERED` status and only for the Email channel. Indicates the type of error: `true` – hard bounce error (permanent, e.g., the mailbox does not exist). `false` – soft bounce error (temporary, e.g., the mailbox is full).
iid	string	A unique identifier for the specific message delivery instance.
mediaType	string	Media type (SMS, Email, Web Push Mobile Push, App Inbox, Widget, In-App).
messageId	int	Message ID.
messageInstanceId	int	Message instance ID.
messageLanguageCode	string	Message language code.
messageName	string	Message name (empty for test emails).
messageTag	string	Message tag.
mobilepush	string	Mobile app subscriber token.
osName	string	Device operating system.
osType	string	Device type (Desktop/Mobile).
sms	string	Contact phone number.
sourceEventId	int	Source event ID.
sourceEventKey	string	Source event key.
sourceEventTypeKey	string	Source event type key.
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.
subscriptions	array of strings	Subscription category keys.
viewMessageLink	string	Link to the web version of the message (Email only).
webpush	string	Web push subscriber token.
workflowBlockId	string	Identifier of the workflow block that sent the message.
workflowId	int	Workflow ID.
workflowInstanceId	uuid	The identifier of a particular workflow launch. Use it to group campaigns within the launch of a workflow.

Below are webhook test examples as a JSON array with all possible status options.

Bulk campaign:

[
  {
    "broadcastId": 3459207,
    "messageName": "test",
    "iid": "99d591ab-e7a5-49ed-8e16-b3023378fc18",
    "contactId": 1967597908,
    "externalCustomerId": "789456512",
    "email": "[email protected]",
    "mediaType": "email",
    "activityStatus": "DELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702518,
    "activityDateTime": "2023-09-14T08:30:03",
    "viewMessageLink": "https://u51739.esclick.me/J9o6EvyAKGmB"
  },
  {
    "broadcastId": 3459207,
    "messageName": "test",
    "iid": "4af20897-de88-4ad0-ada3-dc4bcf14e8d8",
    "contactId": 889891911,
    "externalCustomerId": "262ac297-6ae1-11ec-a2ec-0050569bdf92",
    "email": "[email protected]",
    "mediaType": "email",
    "activityStatus": "DELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702518,
    "activityDateTime": "2023-09-14T08:30:03",
    "viewMessageLink": "https://u51739.esclick.me/J9o6Dl1wrDeB"
  },
  {
    "broadcastId": 3459207,
    "messageName": "test",
    "iid": "b14dec37-806e-4bc4-ba71-a5911a7d7ce4",
    "contactId": 1026901517,
    "email": "[email protected]",
    "mediaType": "email",
    "activityStatus": "DELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702518,
    "activityDateTime": "2023-09-14T08:30:03",
    "viewMessageLink": "https://u51739.esclick.me/J9o6Dttf6fOB"
  },
  {
    "broadcastId": 3459207,
    "messageName": "test",
    "hardBounce": false,
    "iid": "99d591ab-e7a5-49ed-8e16-b3023378fc18",
    "contactId": 1967597908,
    "externalCustomerId": "789456512",
    "email": "[email protected]",
    "mediaType": "email",
    "activityStatus": "UNDELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702518,
    "activityDateTime": "2023-09-14T08:30:07",
    "statusDescription": "5.1.2 (bad destination system: no such domain)",
    "viewMessageLink": "https://u51739.esclick.me/J9o6EvyAKGmB"
  }
]

Triggered campaign:

[
  {
    "messageName": "test",
    "workflowId": 340484,
    "workflowBlockId": "_05cae26d9ae85e1eb40ed34765f9c7be",
    "sourceEventKey": "9d0c163d-cc3b-4f9e-bb03-2f5d1111ef91",
    "sourceEventTypeKey": "productViewed",
    "workflowInstanceId": "da33697d-52d8-11ee-9d24-7ec2059b5114",
    "iid": "019b7450-52d9-11ee-85c4-959256ea468c",
    "contactId": 889891911,
    "externalCustomerId": "262ac297-6ae1-11ec-a2ec-0050569bdf92",
    "email": "[email protected]",
    "mediaType": "email",
    "activityStatus": "DELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702524,
    "activityDateTime": "2023-09-14T08:30:50",
    "viewMessageLink": "https://u51739.esclick.me/1RocjPwr0MwONsdn2P"
  },
  {
    "messageName": "test",
    "workflowId": 340484,
    "workflowBlockId": "_527e1f819b41bd379d75ebbe3392b879",
    "sourceEventKey": "9d0c163d-cc3b-4f9e-bb03-2f5d1111ef91",
    "sourceEventTypeKey": "productViewed",
    "workflowInstanceId": "da33697d-52d8-11ee-9d24-7ec2059b5114",
    "iid": "01777190-52d9-11ee-917a-ef6e91bfc7c3",
    "contactId": 889891911,
    "externalCustomerId": "262ac297-6ae1-11ec-a2ec-0050569bdf92",
    "email": "[email protected]",
    "mediaType": "email",
    "activityStatus": "DELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702524,
    "activityDateTime": "2023-09-14T08:30:51",
    "viewMessageLink": "https://u51739.esclick.me/1RocjPwr0MwONsd3gP"
  },
  {
    "messageName": "test",
    "workflowId": 340484,
    "workflowBlockId": "_be178ec8aacbf249d8bb736e9df9fd0d",
    "sourceEventKey": "9d0c163d-cc3b-4f9e-bb03-2f5d1111ef91",
    "sourceEventTypeKey": "productViewed",
    "workflowInstanceId": "da33697d-52d8-11ee-9d24-7ec2059b5114",
    "hardBounce": false,
    "iid": "01a86ca0-52d9-11ee-85c4-959256ea468c",
    "contactId": 706515632,
    "sms": "380956490955",
    "mediaType": "viber",
    "activityStatus": "UNDELIVERED",
    "messageId": 3213684,
    "messageInstanceId": 4696769,
    "messageTag": "tag2,tag,test",
    "activityDateTime": "2023-09-14T08:30:51",
    "statusDescription": "401: null"
  }
]

Alternative Methods for Tracking Activity Statuses

For comparison/alternative, the API method Get contacts activity is used.

It works by sending GET requests from your side, where you can specify a time interval (up to 3 months) and parameters (such as email, status, etc.).