PUSHTech™ API Icon

Webhooks


PushTech can make an HTTP POST to your URLs when events occurs. If you would like Pushtech to POST event notifications, you need to configure a callback URL in the Webhooks section in your account.


Configuration

In Api section of your account, you can find the Webhooks section. In this section you will find where to add your Urls to use with the webhook events. The webhook events are organised by channel for the delivery messages or organised by type for the contact activities.

HTTP status code

For Webhook POSTs, Pushtech listens for the following codes from your server and reacts accordingly:
  • if Pushtech receives a 200 (Success) code it will determine the webhook POST is successful and will not retry.

  • If Pushtech receives a 406 (Not Acceptable) code, it will determine the POST is rejected and will not retry.

  • For any other code, Pushtech will retry POSTing according to the schedule below for Webhooks other than the delivery events.

If your application is unable to process the webhook request but you do not return a 406 error code, Pushtech will retry (other than for delivery events) during 4 hours at the following intervals before stop trying: 5 minutes, 5 minutes, 10 minutes, 10 minutes, 30 minutes, 1 hour and 2 hours.

Securing Webhooks

To ensure the authenticity of each webhook requests, Pushtech signs them and posts the signature along with other webhook parameters:
Parameter Type Location Description
timestamp int Body parameter Number of seconds passed since January 1, 1970.
token string Body parameter Randomly generated string with length 50.
Authorization token string Authorization header String with hexadecimal digits generate by HMAC algorithm.

To verify the webhook is originating from Pushtech you need to:

  • Concatenate timestamp and token values.

  • Encode the resulting string with the HMAC algorithm (using your Account secret Key as a key and SHA256 digest mode).

  • Compare the resulting hexdigest to the Authorization token

  • Optionally, you can check if the timestamp is not too far from the current time.

Below is a PHP code sample used to verify the Authorization token:
function verify($account_secret_key, $token, $timestamp, $authorization) {
    $data = $timestamp . $token;
    return hash_hmac('sha256', $data, $account_secret_key) == $authorization;
}

And here’s a sample in Python:
import hashlib, hmac

def verify(account_secret_key, token, timestamp, authorization):
  hmac_digest = hmac.new(key=account_secret_key,
    msg='{}{}'.format(timestamp, token),
    digestmod=hashlib.sha256).hexdigest()
  return hmac.compare_digest(unicode(authorization), unicode(hmac_digest))

And here’s a sample in Ruby:
require 'openssl'
def verify(account_secret_key, token, timestamp, authorization)
  digest = OpenSSL::Digest::SHA256.new
  data = [timestamp, token].join
  authorization == OpenSSL::HMAC.hexdigest(digest, account_secret_key, data)
end

Reference

In case of activities, Pushtech will return this parameters in json format in body request:

Parameter Description
created_at The activity created date
_id The activity id
origin The origin of metric. Values [api, sdk, campaign]
type Describe the activity type. Values: [event, update, custom ,open_app , uninstall_app, subscribe_push, unsubscribe_push, add_cart, remove_cart,product_view , product_refund, purchase_failed, gps_location , contact_status]
event_type Describe a type of event related with campaigns. Values [opened, delivered, clicked, unsubscribed, sent, failed]
updated_field The name of field updated, only available if type is 'update'
updated_field_value The value of updated field, only available if type is 'update'
custom The custom raw metric,only available if type is 'custom' and origin is 'sdk'
custom_key The key of custom metric,only available if type is 'custom'
custom_value The value of custom metric,only available if type is 'custom'
old_status The old status of contact, only available if type is 'contact_status'
current_status Contact status, only available if type is 'contact_status'
contact[_id] Id of the contact
contact[user_id] Custom user_id of the contact
contact[device_id] Associated device_id
contact[name_first] First name of the contact
contact[name_last] Last name of the contact
contact[email] Email of the contact
contact[phone] Phone number with country code of the contact
app[_id] Id of app,only available if origin is 'sdk'
app[name] Name of the app,only available if origin is 'sdk'
app[icon] Icon of the app,only available if origin is 'sdk'
campaign[_id] Id of campaign,only available if origin is 'campaign'
campaign[name] Name of campaign,only available if origin is 'campaign'
product[UUID] Uniquee identifier of product, only available if type related with purchase or product
product[name] Name of product, only available if type related with purchase or product
product[price] Price of product, only available if type related with purchase or product
product[currency] Currency of product, only available if type related with purchase or product

Example of activity json:

{
  "created_at":"2016-12-09T15:28:28Z",
  "_id":"584acd9c85216d892f000002",
  "origin":"campaign",
  "type":"event",
  "event_type":"sent",
  "contact": {
    "_id": "584acff2f92ea1bcf7000012",
    "user_id": "jhon_doe",
    "name_first": "Jhon",
    "name_last": "doe",
    "email": "Jhon.doe@pushtech.com",
    "phone": "+346xxxxxxxx",
    "device_id": "5848408485216d13d1000009"
  },
  "campaign":{
    "_id":"5848408485216d13d100000a",
    "name":"Welcome email"
  },
  "timestamp":1481297309,
  "token":"9ykzr1m09d3jgq04k5j2htlf0rs7wy93rtniaes6v3lyk2scm7"
}

In case of deliveries, Pushtech will return this parameters in json format in the body request:

Parameter Description
id The delivery id
created_at The delivery created date
updated_at The delivery updated date
channel The delivery channel, Values : [sms, push, email]
status The status of delivery, Values : [none, queued, sent, deliverd, opened, clicked, rejected, undefined, undelivered, forbidden_country_code, failed, bounced, unsubscribed, dropped, complained]
refunded If true refunded the money in your account
url Url only available if status is clicked and represent the user url clicked
campaign[_id] Id of campaign, only available if delivery created in Pushtech.com Manager
campaign[name] Name of campaign, only available if delivery created in Pushtech.com Manager
template[_id] Id of template, only available if delivery created in Pushtech.com Manager and channel is email
template[name] Name of template, only available if delivery created in Pushtech.com Manager and channel is email
template_data[sender] Sender of email, only available if delivery created in Pushtech.com Manager and channel is email
template_data[subject] Subject of email, only available if delivery created in Pushtech.com Manager and channel is email
template_data[content] Content of sms or push message, only available if delivery created in Pushtech.com Manager and channel is push or sms
template_data[reply_to] Email to reply to, only available if delivery created in Pushtech.com Manager and channel is email
landing_page_sms[_id] Id of landing page, only available if delivery created in Pushtech.com Manager and channel is sms and contains a landing page link
landing_page_sms[name] Name of landing page, only available if delivery created in Pushtech.com Manager and channel is sms and contains a landing page link
landing_page_sms[url] Url of landing page, only available if delivery created in Pushtech.com Manager and channel is sms and contains a landing page link
landing_page_push[_id] Id of landing page, only available if delivery created in Pushtech.com Manager and channel is push and contains a landing page link
landing_page_push[name] Name of landing page, only available if delivery created in Pushtech.com Manager and channel is push and contains a landing page link
landing_page_push[url] Url of landing page, only available if delivery created in Pushtech.com Manager and channel is push and contains a landing page link
channel_data Data of delivery
contact[_id] Id of the contact, only available if campaign sent with Pushtech.com Manager
contact[user_id] Custom user_id of the contact
contact[name_first] First name of the contact, only available if campaign sent with Pushtech.com Manager
contact[name_last] Last name of the contact, only available if campaign sent with Pushtech.com Manager
contact[email] Email of the contact, only available if campaign sent with Pushtech.com Manager
contact[phone] Phone number with country code of the contact
app[_id] Id of app,only available if campaign sent with Pushtech.com Manager and channel is push
app[name] Name of the app,only available if campaign sent with Pushtech.com Manager and channel is push
app[icon] Icon of the app,only available if campaign sent with Pushtech.com Manager and channel is push
device[_id] Id of device,only available if campaign sent with Pushtech.com Manager and channel is push
device[type] type of the device (ios, android or web), only available if campaign sent with Pushtech.com Manager and channel is push
device[device_push_token] Push token of the device, only available if campaign sent with Pushtech.com Manager and channel is push

Example of delivery json:

 {
  "id":"584acffdf92ea1e99a000001",
  "created_at":"2016-12-09T15:38:37Z",
  "updated_at":"2016-12-09T15:38:49Z",
  "channel":"EMAIL",
  "status":"delivered",
  "refunded":false,
  "url":null,
  "campaign":{
    "_id":"5848408485216d13d100000a",
    "name":"Welcome"
  },
  "template"{
   "_id": "5848408485216d13d1000009",
   "name" : "Welcome"
  },
  "template_data":{
    "sender":"PUSHTech platform ",
    "subject":"",
    "content":"",
    "reply_to":""
  },
  "channel_data":{
    "3":"Jhon.doe@pushtech.com"
  },
  "contact": {
    "_id": "584acff2f92ea1bcf7000012",
    "user_id": "jhon_doe",
    "name_first": "Jhon",
    "name_last": "doe",
    "email": "Jhon.doe@pushtech.com",
    "phone": "+346xxxxxxxx",
    "device_id": "5848408485216d13d1000009"
  },
  "timestamp":1481297931,
  "token":"mcnwldwmullbg4wkcx33ewirm4kmi5vn1i9k30hob5vagdk69w"
}

In case of Bulk contacts, PUSHTech will return this parameters in json format in the body request:

Parameter Description
contacts_valid_count Number of contacts saved in PUSHTech
contacts_failed_count Number of contacts failed to save in PUSHTech
failed_contacts Array that contains failed contacts
failed_contacts[contact] Contact params of a particular failed contact
failed_contacts[error] Description because contact save failed
valid_contacts Array that contains a valid contacts with basic fields: _id, user_id, email, phone_countrycode , phone_number
valid_contacts[_id] Pushtech id of the contact
valid_contacts[user_id] User id of the contact
valid_contacts[email] Email of the contact
valid_contacts[phone_countrycode] Phone country code of the contact
valid_contacts[phone_number] Phone number of the contact

Example of bulk json:

{
  "contacts_valid_count":3,
  "contacts_failed_count":1,
  "failed_contacts":[
                    {
                      "contact":
                        {
                          "name_first":"Doria",
                          "name_last":"Leppiwell",
                          "city":"Shajia’ao",
                          "gender":"Female",
                          "email":"badformat",
                        },
                        "errors":["Email format not recognised"]

                    }
                    ],
  "valid_contacts":[
                  {
                    "_id":"599bf99af70366f2be000001",
                    "user_id":"1",
                    "email":"dleppingwell0@mydomain.com",
                    "phone_countrycode":"34",
                    "phone_number":866666666
                  },
                  {
                    "_id":"599bf99af70366f2be000002",
                    "user_id":"3",
                    "email":"kschapiro1@domain.gov",
                    "phone_countrycode":34,
                    "phone_number":566678888
                  },
                  {
                    "_id":"599bf99af70366f2be000003",
                    "user_id":"2",
                    "email":"acasazza2@domainmarket.com",
                    "phone_countrycode":34,
                    "phone_number":877777777
                  }
                  ],
  "timestamp":1503394216,
  "token":"2m93z8xw1ofoiy890xx23ql9ah0gz60t85nuc9wyshu5apjxtt"
}