Generic selectors
Exact matches only
Search in title
Search in content
Search in posts
Search in pages

Event notification system (Webhooks)

Вы здесь:

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

  • a change of the letter 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).

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

The model used in Webhook works 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.

Install handler

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])
https://api.unisender.com/en/api/setHook?api_key=KEY&hook_url=URL&event_format=FORMAT&events[]=EVENT&max_parallel=NUM
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_formatThe 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 keyDescription
email_statusChange in the status of the sent email. Valid values:

ok_sent — the letter has been sent;
ok_delivered — the letter has been delivered;
ok_read — the letter has been read;
ok_link_visited — a click-through has been registered;
err_will_retry — the letter 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.

unsubscribeChange in the subscription status of the recipient (unsubscribed from the list, subscribed to the list). Valid value:*
subscribeChange 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_primaryChange 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_statusChange of the campaign status.

Valid value: *

email_checkAdding the verified return address.

Valid value: *

user_paymentAvailable only to resellers. Change in the account status. Movements associated with the main and bonus account are taken into account.

Valid value: *

user_infoChange in the user information fields. Valid value: *
max_parallelOptional indication of the maximum number of parallel calls to this handler. The default value is 10.
single_eventIt 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)..

Call example

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

Handlers list

listHooks — get the list of all handlers.

Syntax and URL to call the method
listHooks ()
https://api.unisender.com/en/api/listHooks?api_key=KEY
Arguments
api_key *API access key.
Return value
   
   {
    "result":
        [{
            "id":3,
            "url":"https:\/\/site.com\/unisender-hook",
            "event_format":"json_post_gzip",
            "max_parallel":1,
            "single_event":0,
            "events":
                {
                    "subscribe": ["1","2","3"]
                }
         }]
    }

Remove handler

RemoveHook — remove the notification handler.

Syntax and URL to call the method
removeHook (hook_url)
https://api.unisender.com/en/api/removeHook?api_key=KEY&hook_url=URL
Arguments
api_key *API access key.
hook_url*URL-identifier of the removed handler.

Notice in the JSON format

Example of the notice returned

{ 
  "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":"user@example.com", 
            "campaign_id":"124345", 
            "user_campaign_id":"346134", 
            "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":"user2@example.com", 
            "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":"user2@example.com", 
            "campaign_id":"87434", 
            "user_campaign_id":"camp-5464", 
            "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:

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

authMD5 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 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 md5 of the notification body and compare it with the auth value received in the initial notification body.

numURL 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_userArray 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.
loginLogin of the user, the event notification of whose we transfer in the relevant element of the array events_by_user.
eventsArray of the user events with the above login, each array element has the following fields:

event_nameevent name, one of the following: email_check, unsubscribe, activate, reject, campaign_status, user_payment, user_info, email_status.
event_timethe time of occurrence of the event in the “YYYY-MM-DD hh:mm:ss” format in the UTC time zone.
event_dataobject with the event data the format of which depends on the event name. The formats are described below: *
* Event_data formatDescription
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.
  • user_campaign_id — only if it was specified by the user when sending.
  • 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 letter from which contact used to unsubscribe;
  • user_campaign_id — optional user identifier of the campaign, the letter from which was used to unsubscribe. It is absent if the user has not transferred his campaign identifier to sendEmail/createCampaign.
  • list_id — either “0”, or the code of the list on which the letter was sent, after which the unsubscription was made. “0” means that all lists have been unsubscribed.
  • just_unsubscribed_list_ids — 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 — optional array of list codes that have just been subscribed to (you can also return subscription on the unsubscribe page). It is absent if there was an unsubscription from all lists or and 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 letters;
  • currency — three-letter international currency code, in which the amount due for sending letters was calculated (RUB, USD, EUR, UAH).
email_checkEmail — 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