Webhook Notifications

In this Article:

What is a Webhook notification?

In ECAL, you can register 1 or more webhooks to receive POST notifications whenever a User subscribes via your ECAL widget(s). There are 2 reason you may consider using Webhooks.

  1. Receiving Subscriber data in real-time so you can update your CRM.
  2. Receiving the Subscriber’s ECAL_ID upon subscription. Allowing you to interact with that individual’s calendar via the ECAL API.

If you are using Private Events in ECAL, you must setup a webhook to receive the Subscriber’s ECAL_ID. For more information on Private Events, see our guide.

How it works

When a User successfully subscribes using your ECAL Widget, ECAL will send a POST notification to all of the callback URLs you have registered. At minimum this will contain the new Subscriber’s ECAL_ID and email, as well as any addition registration information you have configured your widget to collect.

How to setup your webhook

To setup a webhook, login to your ECAL Admin (www.ecal.com/login) and click Developers > Webhooks in the side menu. From here you can register a new callback URL as well as activate/deactivate and edit existing callbacks.

When registering a callback URL you have the option to specify an Encryption Secret Key. If provided, ECAL will encrypt all notifications sent to your callback URL using this value as the secret key. For more detail, refer to “Decrypting the payload” information of the “Processing notifications” section below.

ecal_image

Processing notifications

When a notification is received it will contain at minimum 3 elements…

  • ecalId - The ID used to interact with the Subscriber’s ECAL calendar.

  • email - The email address the Subscriber gave when subscribing. Note: if you pass an email address to the ECAL Widget (e.g via the embed code), this email address will be the value delivered here to the notification. This allows you to easily associate the Subscriber with the originating User account in your own platform.

  • timestamp - A unix timestamp denoting the time the user subscribed.

In addition to the above basic elements, the payload may also contain location data and any data requested of the Subscriber during the subscription process such as what Calendars they have chosen to subscribe to (if any).

It is recommended that upon receiving a notification, all information is stored against the User record within your own platform.

The following is an example of a common payload you might receive. In this case, the Publisher hasn’t asked for any additional user details via the ECAL widget, and as such, only a subset of the fields are delivered.

The Notification Payload

EXAMPLE NOTIFICATION:

POST https://www.yourcallbackurl.com/
{
    "ecalId": "57e9547dd8178cf324f737c4",
    "email": "joe.user@gmail.com",
    "timestamp": "1513568248",
    "calendarNames": [
        "AAdvantage Aviator",
        "Barclaycard Visa"
    ],
    "calendarIds": [
        "57a22c28e0ee0825664e7774",
        "59c51af05b5a42f21b8b4567"
    ],
    "calendarReference": [
        "AAdvantage-Aviator",
        "Barclaycard-Visa"
    ],
    "location": {
        "country_code" : "AU",
        "country_name" : "Australia",
        "state_code" : "VIC",
        "state_name" : "Victoria",
        "zip_code" : "3004",
        "city_name" : "Melbourne",
        "latitude" : -37.814,
        "longitude" : 144.9633
    }
}

Fields

Field Type Required Example
age_group String NO 25-34
calendarids Array [String] NO 
{
 [ “57a22c28e0ee0825664e7774”, “59c51af05b5a42f21b8b4567”] 
}
calendarNames Array [String] NO [ “AAdvantage-Aviator”,“Barclaycard-Visa” ]
Country String NO US
custom_fields Array [Object] NO 
 
 {
 “name” : “Favourite Team”, “value” : “Manchester United” }, 
{ “name” : “Date of Birth”,  “value” : “1979-08-12” }, 
{  “name” : “Over 13 yrs”,  “value” : “Yes” }, 
{ “name” : “Country Code”,  “value” : “sd” }
ecalid String YES 57e9547dd8178cf324f737c4
email String YES rfitz@gmail.com
first_name String NO Ryan
gender String NO M
last_name String NO Fitzgerald
location Object NO { “country_code” : “AU”, “country_name” : “Australia”, “state_code” : “VIC”, “state_name” : “Victoria”, “zip_code” : “3004”, “city_name” : “Melbourne”, “latitude” : -37.814, “longitude” : 144.9633 }
mobile String NO +61444444444
timestamp Integer YES 1513568248
zip String NO 06716

Decrypting the Payload

If you have specified a Secret key when registering your Callback URL, all POST made to your url will be encrypted.

EXAMPLE ENCRYPTED NOTIFICATION

POST https://www.yourcallbackurl.com/
{
    "payload": "6AXjTO\/pq\/PQ8rEiDIsOhARiCoroKf3t+ESJvDkljJAiy8v88Ixon2RDu81WNY1W0mIVZEWzMFZa2Zd0eI8vF2FTnc4MAa3a+j1DN2u1Z\/FrzWZg4M9KYGPGIsIu962IwtQsWqbFo6Dd5165\/fn9bf50xweu6tXh6J3s0tXieMO03cQobEYK5csBciB09J7PHA6CrK8iRsxww32XrsnAxHTURqT1VSv19eocxblfPigYmpMSpEy5mb6JOzLCEcBebPJaxfFnB0iHfrZpnH30+497EZryOQSFJox0r9r7Tbv1PMzdJ0NLZsq+e4MJPvUO6YQ+xyzmRzYbfmb0w1dk2FmPazPWICo8vDgi3R8ouhpFQfRLc6b8XsDqpU2kyq5ltLSBbBFpoHdzgP1PI+bk+W\/m2P0OTz+p5gTvTOqABXgPy74VDQIS2iqS1gigmFcXmHh5styQFVn0FZEAzOiyFsBzohEn4iZPwDlX\/ltBg1QOLIR4hMbe1QF9iDn6rnt63PEbXAWuTkzXc9B5uzR9WN5ZWUgWlbFuEmjrKruZSJTh0clH5EBLRqHDjuJH3hyDX7MxV+ud6KNEs6ZGt14Uckg83YA7K65oj\/iUix47QCTt5jdCXgNL3o4xEMES\/GiubO9ZiAEzmiS5LrwRdJ3UWsCkfSVlLURusu9ubVHxqNOacv7hzpOmEWqXM1Qj+aUay\/\/vcZWyU+z+ZU2eFox6T3ia3aWTiOoBSwBUrWtOwgY="
}

To decrypt the payload, follow these steps.

  1. base64 decode the string contained in the payload value.
  2. create a Block with your 32 byte secret key (if not 32 bytes, you need to repeat your secret key up to 32 bytes)
  3. Using that block, get a GCM.
  4. Using that GCM, Open your decoded payload

The following example demonstrates how this would look in …. …

If you require any additional information, please contact support@ecal.com or live chat with us on ecal.com.

Managing failed notifications

It is possible, for a variety of reason, that some notifications might fail to deliver to your callback. In this situation, ECAL will attempt to resend the notification 3 more times over the course of 1 hour. After all retry attempts have been made, ECAL will stop attempting delivery of the failed notification.

To ensure no Subscriptions are lost in the event of failed delivery, all subscriptions will also be delivered to you via our nightly Data Delivery Service (speak to your ECAL support team to set this up).

You will be able to identify Subscribers who you weren’t notified of as their will be information, similar to the following, in the webhook_notification_failed column.

EXAMPLE webhook_notification_failed DATA

POST https://www.yourcallbackurl.com/
[
   { "url":"http:\/\/your.callbackurl.com/", "reason":"dial tcp your.callbackurl.com:80: getsockopt: connection refused" },
   { "url":"http:\/\/a.different.callbackurl.com", "reason":"dial tcp a.different.callbackurl.com:80: getsockopt: connection refused" }
]