Перейти к содержимому

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 TypeDescriptionReturned DataExample JSON
Email — SendTriggered when an email is sent.eventType: Event type (EmailSends) eventDate: Event date and time
messageId: Message ID
subscriberId: Subscriber ID subscriberEmail: Subscriber email
customSubscriberId : Custom subscriber ID
messageSubject: Message subject
messageTags: Message tags		{«eventType»: «EmailSends», «eventDate»: «2024-05-08T13:41:52.4514466Z», «messageId»: 145413, «subscriberId»: 6552353, «subscriberEmail»: «test@test.com«,
«customSubscriberId»: «testId»,
«messageSubject»:
«Subject test»,
«messageTags»: [
«tag1»,
«tag2»]
}
Email — ClickTriggered 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 — OpenTriggered 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 — DeliveryTriggered 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 — BounceTriggered 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 — ComplaintTriggered 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«}
SubscriptionTriggered 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 ConfirmationTriggered 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}
UnsubscriptionTriggered when a subscriber unsubscribes from the mailing list.eventType: Event type (Unsubscriptions) eventDate: Event date and time
listId: Mailing list ID subscriberId: Subscriber ID
unsubscribeReason: Unsubscribe reason*
subscriberEmail: Subscriber email		{«eventType»: «Unsubscriptions», «eventDate»: «2024-05-10T12:58:06.2247049Z», «listId»: 7468,
«subscriberId»: 4723542,
«unsubscribeReason»: «Api»
«subscriberEmail»: «test@test.com«}

* Available unsubscribe reason:

OptOutLinkSubscriber unsubscribed using Unsubscribe link
UiSubscriber was manually removed from the list
BlacklistSubscriber blacklisted
BounceLimitThe subscriber’s email address caused bounces
ComplaintSubscriber reported messages received as spam/abuse
UserUnknownSubscriber email address caused user bounce unknown
ApiSubscriber has been removed from the list by the API
SyncImportSubscriber was removed from the list during list synchronization (import)

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:

ParameterDescription
Occurrence DateDate and time when the Webhook delivery attempt occurred.
Webhook NameUnique name assigned to the Webhook during configuration.
Webhook IDUnique identifier of the Webhook.
StatusServer response status, e.g., HTTP error code.
Error ContentDetailed information about the error returned by the server.
Webhook PayloadData 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.

Privacy policy