Webhooks
INTRODUCTION #
Webhooks in ExpertSender enable automatic notifications to external systems about events occurring in your application. With Webhooks, ExpertSender can send event information to other systems in real-time, allowing for quick reactions and integrations with various tools and services. By using Webhooks, you can automate processes, monitor events, and synchronize data without the need for continuous API polling.
WEBHOOK CREATOR AND CONFIGURATION #
Starting the Wizard:#
- Log in to the ExpertSender admin panel.
- Go to the Automation tab.
- Navigate to the Webhooks section.
- Click the “Create new Webhook” button to start the wizard.
Webhook Configuration:#
- Name: Enter a unique name for your Webhook for easy identification.
- Event: Select the type of event that will trigger the Webhook (e.g., “Email – Open”, “Email – Delivery”).
- Target URL: Enter the URL where notifications should be sent. Ensure the URL is correct, publicly accessible, and a valid HTTPS address.
Before Activating the Webhook: #
Connection Test: The system will check if the URL and event type fields are correctly filled and if the entered URL is a valid HTTPS address.
The connection test verifies:
- The fields for the address and event type are filled.
- The entered address is a valid HTTPS address.
- Sends dummy data to the specified address.
- Data structure matches the event type.
- Connection errors are presented similarly to WebHook logs. Uniqueness Check: The system checks if there is no other active WebHook for the selected event type.
Webhooks are automatically activated upon creation. Editing a Webhook is only possible for inactive Webhooks, so re-checking these conditions is not required during editing.
Testing and Activation: #
After entering all the data and successfully passing the connection test, the Webhook will be automatically activated.
EVENT TYPES #
We have the following event types:
| Event Type | Description | Returned Data | Example JSON |
|---|---|---|---|
| Email – Send | Triggered when an email is sent. | eventType: Event type (EmailSends) eventDate: Event date and time messageId: Message ID subscriberId: Subscriber ID subscriberEmail: Subscriber email | {“eventType”: “EmailSends”, “eventDate”: “2024-05-08T13:41:52.4514466Z”, “messageId”: 145413, “subscriberId”: 6552353, “subscriberEmail”: “test@test.com“} |
| Email – Click | Triggered when a subscriber clicks a link in the email. | eventType: Event type (EmailClicks) eventDate: Event date and time messageId: Message ID subscriberId: Subscriber ID subscriberEmail: Subscriber email | {“eventType”: “EmailClicks”, “eventDate”: “2024-05-10T09:30:00.8726192Z”, “messageId”: 148000, “subscriberId”: 1, “subscriberEmail”: “test@test.com“} |
| Email – Open | Triggered when a subscriber opens an email. | eventType: Event type (EmailOpens) eventDate: Event date and time messageId: Message ID subscriberId: Subscriber ID subscriberEmail: Subscriber email | {“eventType”: “EmailOpens”, “eventDate”: “2024-05-10T13:28:23.2093755Z”, “messageId”: 149211, “subscriberId”: 5823952, “subscriberEmail”: “test@test.com“} |
| Email – Delivery | Triggered when an email is delivered to the recipient. | eventType: Event type (EmailDeliveries) eventDate: Event date and time messageId: Message ID subscriberId: Subscriber ID subscriberEmail: Subscriber email | {“eventType”: “EmailDeliveries”, “eventDate”: “2024-05-09T10:29:36.8300628Z”, “messageId”: 145413, “subscriberId”: 6552353, “subscriberEmail”: “test@test.com“} |
| Email – Bounce | Triggered when an email cannot be delivered (error). | eventType: Event type (EmailBounces) eventDate: Event date and time messageId: Message ID subscriberId: Subscriber ID subscriberEmail: Subscriber email | {“eventType”: “EmailBounces”, “eventDate”: “2024-05-09T09:33:29.6409191Z”, “messageId”: 138876, “subscriberId”: 149448, “subscriberEmail”: “test@test.com“} |
| Email – Complaint | Triggered when a recipient reports an email as spam. | eventType: Event type (EmailComplaints) eventDate: Event date and time messageId: Message ID subscriberId: Subscriber ID subscriberEmail: Subscriber email | {“eventType”: “EmailComplaints”, “eventDate”: “2024-05-09T13:17:45.494757Z”, “messageId”: 149141, “subscriberId”: 49858, “subscriberEmail”: “test@test.com“} |
| Subscription | Triggered when a new subscriber joins the mailing list. | eventType: Event type (Subscriptions) eventDate: Event date and time listId: Mailing list ID subscriberId: Subscriber ID subscriberEmail: Subscriber email | {“eventType”: “Subscriptions”, “eventDate”: “2024-05-10T11:52:50.4969976Z”, “listId”: 7477, “subscriberId”: 6552356, “subscriberEmail”: “test@test.com“} |
| Subscription Confirmation | Triggered when a subscriber confirms their subscription to the mailing list. | eventType: Event type (Confirmations) eventDate: Event date and time messageId: Message ID subscriberId: Subscriber ID subscriberEmail: Subscriber email listId: Mailing list ID | {“eventType”: “Confirmations”, “eventDate”: “2024-05-13T11:21:12.1358311Z”, “messageId”: 149212, “subscriberId”: 5823952, “subscriberEmail”: “test@test.com“, “listId”: 7480} |
| Unsubscription | Triggered when a subscriber unsubscribes from the mailing list. | eventType: Event type (Unsubscriptions) eventDate: Event date and time listId: Mailing list ID subscriberId: Subscriber ID subscriberEmail: Subscriber email | {“eventType”: “Unsubscriptions”, “eventDate”: “2024-05-10T12:58:06.2247049Z”, “listId”: 7468, “subscriberId”: 4723542, “subscriberEmail”: “test@test.com“} |
LOGS AND RETRIES #
Webhook Logs #
In the case of failed Webhook deliveries, detailed logs are available containing the following information, accessible in the ExpertSender panel under Audit -> Webhook Logs:
| Parameter | Description |
|---|---|
| Occurrence Date | Date and time when the Webhook delivery attempt occurred. |
| Webhook Name | Unique name assigned to the Webhook during configuration. |
| Webhook ID | Unique identifier of the Webhook. |
| Status | Server response status, e.g., HTTP error code. |
| Error Content | Detailed information about the error returned by the server. |
| Webhook Payload | Data sent within the Webhook. |
These logs are available in the ExpertSender panel, enabling tracking of failed delivery attempts and helping diagnose and resolve integration issues with Webhooks. They also allow monitoring of delivery success and quick response to errors.
SECURITY #
To ensure the security and authenticity of Webhook calls, it is recommended to:
- Use HTTPS for data transmission.
- Validate requests at the receiving server level.
- Use authentication tokens to verify the request source.
This documentation aims to facilitate the integration of Webhooks with your application and ensure quick and efficient event management in real-time.