Event notification system (Webhooks)

Webhook is a mechanism designed to notify system users about events. Events that the Webhook can notify about:

a change of the email status (sent, delivered, rejected, read, the recipient followed the link);
the contact has unsubscribed from the list/subscribed to another list;
a change in the campaign status;
a change in the user data;
adding the verified return address;
a change in the account status;
adding a new user (for resellers).

The Webhook is used to track changes in the email status in real time.

Webhook operates as follows: when an event occurs, the previously installed handler sends JSON to the URL that was indicated for this Webhook. Standard ports are used: port 80 for HTTP and port 443 for HTTPS. To install Webhook on the URL with the specified port, you can send the URL in the form: http://11.111.111.11:80

If the URL to which the Webhook is sent is unavailable (the HTTP 200 OK does not respond, the timeout is 3 seconds), attempts to send the Webhook to this URL, until the expected 200 OK is received, will last for 24 hours with an interval of 10 minutes with the additional retry_count parameter, which will increase by 1 after each Webhook re-sending.

If the Webhook fails to be successfully delivered within 24 hours, the attempts stop, and the Webhook status is changed to stopped. An email is sent to the account about the Webhook deactivation and its last response. To reactivate the stopped Webhook, correct the error, then activate it with the setHook API method with the parameter status="active" or change the status in your Account.

Install handler

setHook — install/replace a notification handler for events of a specific type.

Syntax and URL to call the method

setHook (hook_url, events, [event_format, max_parallel, single_event, status])

https://api.selzy.com/en/api/setHook?api_key=KEY&hook_url=URL&event_format=FORMAT&events[]=EVENT&max_parallel=NUM&single_event=1&status=active

Arguments

api_key*

API access key

hook_url *

URL to which a request should be sent when an event occurs. Actually, it is a handler identifier. When you call setHook again with the same hook_url, the handler data will be replaced.

event_format

The format in which event data is transferred, a mandatory parameter with three value options:

json_post — the notification parameters will be transferred in the body of the POST request in the JSON format, several events of different types can be grouped in one request at once;
json_post_gzip — recommended method. It matches the json_post, only the body of the POST request is compressed using gzip;
http_get — outdated option; notification parameters are transferred as GET parameters of the HTTP request; the email_status event is not supported.

events*

Associative array listing notifications received by the handler. The following strings can be the array keys:

Array key	Description
email_status	Change in the status of the sent email. Valid values: ok_sent — the email has been sent; ok_delivered — the email has been delivered; ok_read — the email has been read; ok_link_visited — a click-through has been registered; err_will_retry — the email has not been delivered, but there will be other attempts to resend it. See other valid values here. It is allowed to be used only with json_post_gzip and json_post formats, and prohibited with the http_get format.
unsubscribe	Change in the subscription status of the recipient (unsubscribed from the list, subscribed to the list). Valid value:*
subscribe	Change in the subscription status of the recipient (subscribed to the list). Valid values: * — send in case of subscription to any list; list id — send in case of subscription to the list with the specified id.
subscribe_primary	Change in the subscription status of the recipient (subscribed to the list for the first time). Valid values include: * — send in case of subscription to any list; list id — send in case of subscription to the list with the specified id.
campaign_status	Change of the campaign status. Valid value: *
email_check	Adding the verified return address. Valid value: *
user_payment	Available only to resellers. Change in the account status. Movements associated with the main and bonus account are taken into account. Valid value: *
user_info	Change in the user information fields. Valid value: *

max_parallel

Optional indication of the maximum number of parallel calls to this handler. The default value is 10.

single_event

It obtains the value of 1 or 0. Default value: 0

1 — the Webhook notification does not contain arrays, information will be returned only for one event in one notification;

0 — the Webhook notification returns information in the form of arrays (see example below).

status

Handler status. Permitted values:active — the handler is active; disabled — the handler is deactivated.

Call example

https://api.selzy.com/en/api/setHook?api_key=XXX&hook_url=https%3A%2F%2Fmycompany.com%2Fselzy-hook&event_format=json_post_gzip&events[unsubscribe]=*&events[email_status]=ok_read,ok_link_visited&single_event=1&status=active

Handlers list

listHooks — get the list of all handlers.

Syntax and URL to call the method

listHooks ()

https://api.selzy.com/en/api/listHooks?api_key=KEY

Arguments
api_key *	API access key.

Return value

   
 {
    "result":
        [{
            "id":3,
            "url":"https://site.com/selzy-hook",
            "event_format":"json_post_gzip",
            "max_parallel":1,
            "single_event":0,
            "events":
                {
                    "subscribe": ["1","2","3"]
                },
            "status": "active"
         }]
    }

Remove handler

RemoveHook — remove the notification handler.

Syntax and URL to call the method

removeHook (hook_url)

https://api.selzy.com/en/api/removeHook?api_key=KEY&hook_url=URL

Arguments
api_key *	API access key.
hook_url*	URL-identifier of the removed handler.

Webhook example in the JSON format

Example of the webhook sent

{ 
  "auth":"6931402abc4b2a76b9719d911017c592", 
  "num":"12", 
  "events_by_user": 
  [ 
    { 
      "login":"user_zz", 
      "Events":
      [ 
        { 
          "event_name":"email_status", 
          "event_time":"2015-04-24 15:18:34", 
          "event_data": 
          { 
            "email":"[email protected]", 
            "campaign_id":"124345", 
            "status":"ok_read", 
            "status_group":"success_group",
            "delivery_info":
            {
              "user_agent":"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36",
              "ip":"111.111.111"
            } 
          } 
        }, 
        { 
          "event_name":"email_status", 
          "event_time":"2015-04-24 15:18:36", 
          "event_data": 
          { 
            "email":"[email protected]", 
            "email_id":"346134", 
            "status":"ok_link_visited", 
            "status_group":"success_group",
            "delivery_info":
            {
              "user_agent":"Mozilla/5.0 (X11; Linux x86_64)",
              "ip":"111.111.111"
            }
          } 
        }, 
        { 
          "event_name":"unsubscribe", 
          "event_time":"2015-04-24 15:18:58", 
          "event_data": 
          { 
            "email":"[email protected]", 
            "campaign_id":"87434", 
            "list_id":"3346", 
            "Just_unsubscribed_list_ids":
            [ 
              "3346", "7473" 
            ], 
            "Just_subscribed_list_ids":
            [ 
              "9745" 
            ] 
          } 
        } 
      ] 
    } 
  ] 
}

Description of notification parameters (for single_event = 0)

Notifications in the json_post and json_post_gzip formats are sent in the form of a POST request to the notification URL without additional arguments with Content-Type=application/json (and for json_post_gzip with Content-Encoding: gzip). If json_post_gzip is selected, it is necessary to decompress the GZIP object before reading JSON. The JSON object is transferred in the request body without setting any variables to read the data. For example, you can use the commands on PHP: - gzdecode ($ postData); — for GZIP decompression - file_get_contents ('php: // input'); — for reading JSON.

The notification data is a JSON object with the following fields:

An array of JSON objects, each element of which corresponds to one user. Only resellers may have more than one element in this array — resellers can receive notifications of events from several of their users in one call, in other cases this array consists of one element.

Parameter

Description

auth

MD5 hash of the message string body, in which the auth value is replaced with the api_key of the user whose handler is called. Using this, the notification recipient can both authenticate and verify the integrity of the notification.

To generate auth, you need to form the entire body of the notification in JSON, substitute the auth value of the user's api_key value, and calculate the md5 of the body. Then replace the api_key in the message with the resulting md5 recorded in hexadecimal form in lowercase.

To test auth, you need to replace its value with api_key, also calculate the md5 of the notification body, and compare it with the auth value received in the initial notification body.

num

URL to which a request should be sent when an event occurs. Actually, it is a handler identifier. When you call setHook again with the same hook_url, the handler data will be replaced.

events_by_user

events

An array of the user events with the above login, each array element has the following fields:

event_name	event name, one of the following: email_check, unsubscribe, activate, reject, campaign_status, user_payment, user_info, email_status.
event_time	the time of occurrence of the event in the "YYYY-MM-DD hh:mm:ss" format in the UTC time zone.
event_data	object with the event data the format of which depends on the event name. The formats are described below.

Event_data format	Description
email_status	email — the contact's email, the message delivery status for which has been changed; email_id — message identifier received using the sendEmail. Only for messages sent using sendEmail. campaign_id — only for messages sent using createCampaign. status — message delivery status. status_group — status group in accordance with the names from the email sending results: "not_sent_group", "not_allowed_group", etc.
unsubscribe	email — email of the unsubscribed contact; campaign_id — campaign identifier, the email the contact unsubscribed from; list_id — either "0", or the code of the list to which the email was sent, after which the unsubscription was made. "0" means that all lists have been unsubscribed. just_unsubscribed_list_ids — an optional array of list codes that have just been unsubscribed. It is absent if there was a global unsubscription from all lists (including future ones). just_subscribed_list_ids — an optional array of list codes that have just been subscribed to (you can also return the subscription on the unsubscribe page). It is absent if there was an unsubscription from all lists or if there was no subscription to any lists.
campaign_status	campaign_id — campaign identifier that was returned by the call of the createCampaign method; status — campaign status; contact_count — number of contacts in the campaign list; period_messages — number of messages sent due to those included in the period. For SMS messages, it is always 0; prepaid_messages — number of messages sent due to those purchased before; pay_sum — amount due for sending emails; currency — three-letter international currency code, in which the amount due for sending emails was calculated (USD, EUR, UAH).
email_check	Email — email, the right to use which as a return address is confirmed by the user.
user_payment	sum sum_bonus currency description new_balance new_balance_bonus
user_info	email firstname middlename phone company timezone master country language rights

Managing Webhooks from the Account

In your Account, click on your email in the top right-hand side corner and choose Settings.

From your profile, go to the Settings menu

In the toolbar on the left, select the Webhook section.

From the Settings menu, select Webhook

Here you will find:

The Webhook ID.
The URL with the Webhook.
Maximum number of parallel calls.
The events that your Webhook notifies about.
The Webhook status — active, disabled, or stopped.
The button to remove the Webhook.
The history of errors, if any.

If you need to disable the active Webhook, click on the Active button.

Deactivation of the active Webhook.

To activate the disabled Webhook, click on the Disabled button.

If the Webhook is stopped due to some errors, you can activate it by clicking on the Stopped button.

If there were any errors when the Webhooks were sent to your URL, click on the Error History option to analyze them.