In ECAL, you can register one 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.
If you are using Private Events in ECAL, you must setup a webhook to receive the Subscriber’s ecalId. For more information on Private Events, see our guide.
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 ecalId and email, as well as any addition registration information you have configured your widget to collect.
To setup a webhook, login to your ECAL Admin (https://admin.ecal.net/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.
When a notification is received, it will contain at least 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.
Example
The following is an example of a common payload fields you might receive upon a successful user registration, or re-subscription using the ECAL widget. 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.
POST https://www.yourcallbackurl.com/
{
"ecalId": "57e9547dd8178cf324f737c4",
"email": "joe.user@gmail.com",
"timestamp": "1513568248",
"calendarNames": [
"AAdvantage Aviator",
"Barclaycard Visa"
],
"calendarIds": {
"1": "57a22c28e0ee0825664e7774",
"2": "59c51af05b5a42f21b8b4567"
},
"calendarReferences": [
"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
},
"custom_fields": [
{
"name" : "Favourite Team", "value" : "Manchester United"
},
{
"name" : "Date of Birth", "value" : "1979-08-12"
},
{
"name" : "Over 13 yrs", "value" : "Yes"
}
],
"reference": "ref-1233_$valid"
}
The Manage My ECAL portal also produces webhook notifications for certain actions that the user might perform. Such as:
POST https://www.yourcallbackurl.com/
{
"ecalId": "57e9547dd8178cf324f737c4",
"email": "joe.user@gmail.com",
"timestamp": "1513568248",
"calendarNames": [
"AAdvantage Aviator",
"Barclaycard Visa"
"Citi Aadvantage" // the new schedule added to the subscription
],
"calendarIds": {
"1": "57a22c28e0ee0825664e7774",
"2": "59c51af05b5a42f21b8b4567"
"3": "6566bdc6ceca107e1ee1277c"
},
"calendarReferences": [
"AAdvantage-Aviator",
"Barclaycard-Visa",
"Citi Aadvantage"
],
"reference": "ref-1233_$valid"
}
POST https://www.yourcallbackurl.com/
{
"ecalId": "57e9547dd8178cf324f737c4",
"email": "joe.user@gmail.com",
"timestamp": "1513568248",
"calendarNames": [ // the new state of the subscription minus the removed schedule
"AAdvantage Aviator",
"Citi Aadvantage"
],
"calendarIds": {
"1": "57a22c28e0ee0825664e7774",
"2": "6566bdc6ceca107e1ee1277c"
},
"calendarReferences": [
"AAdvantage-Aviator",
"Citi Aadvantage"
],
"reference": "ref-1233_$valid"
}
POST https://www.yourcallbackurl.com/
{
"ecalId": "57e9547dd8178cf324f737c4",
"email": "joe.user@gmail.com",
"timestamp": "1513568248",
"reference": "ref-1233_$valid",
"action": "unsubscribe"
}
Field | Type | Required | Example |
---|---|---|---|
age_group | String | NO | 25-34 |
calendarIds | Object | NO | { |
calendarNames | Array [String] | NO | [ “AAdvantage-Aviator”,“Barclaycard-Visa” ] |
calendarReferences | Array [String] | NO | [ “AA-Aviator-Ref”,“B-Visa-Ref” ] |
country | String | NO | US |
custom_fields | Array [Object] | NO | [ |
ecalid | String | YES | 57e9547dd8178cf324f737c4 |
String | YES | rfitz@gmail.com | |
first_name | String | NO | Ryan |
gender | String | NO | M |
last_name | String | NO | Fitzgerald |
location | Object | NO | { |
mobile | String | NO | +61444444444 |
timestamp | Integer | YES | 1513568248 |
zip | String | NO | 06716 |
reference | String | NO | ref-1233_$valid |
state | Object | NO | |
action | String | YES | Only unsubscribe for unsubscriptions using the Manage My ECAL Portal |
If you have specified a Secret key when registering your Callback URL, all POST
made to your url will be encrypted.
Example
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.
If you require any additional information, please contact support@ecal.com or live chat with us on ecal.com.
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.
Subscriptions will also be delivered to you via our Data Delivery Service. You can use it to ensure that no Subscriptions are missed in the event of a failed delivery.