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.

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.

   
 {
    "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.

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.

Managing Webhooks from the Account

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

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

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.

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.