Webhook Formats

Modified on Fri, 25 Nov 2022 at 10:23 AM

Webhook Formats

Every webhook request is a standard POST request with a JSON-encoded payload that will contain the eventType key, as a bare minimum. This parameter corresponds to the Event Type you have set up your webhook to listen for, in your Webhook settings, as outlined in our Webhook Management documentation. Please refer to this documentation for more information about how Tall Bob handles your webhook URL being unable to accept requests.

Note:  
Changes that do not remove or modify the expected behaviour of existing parameters are considered backwards-compatible. As a result, new keys may be added for webhooks without advance notice or versioning.

Webhook Data Definitions

Below is a list of webhook event types and the data formats returned for each one.

A message prepared for delivery

At the start of a campaign, we check all recipients for their validity and current subscription status. If everything passes, we are ready to proceed with the send and this event is triggered.

ParameterTypeDescription
eventTypestringData category for this event
timestampintegerTimestamp in epoch time
eventIDstringID for this event
campaignIDstringID for the campaign
campaignNamestringName of the campaign
contactIDstringThe ID of the message recipient (Contact)
recipientstringRecipient phone number (or email)
addressstring(Deprecated) Recipient phone number (or email)
statusstringMessage send status at above timestamp

Example Payload

{
"eventType": "message_polling",
"timestamp": 1583377885,
"eventID": "00011312-5e8f-11ea-b79b-0634275fc628",
"campaignID": "ed742e82-5e75-11ea-be99-061c79b2f7ce",
"campaignName": "webhooks",
"contactID": "8d38d7fc-daa9-11e9-bbe2-029c13ef7f22",
"recipient": "61411118802",
"address": "61411118802",
"status": "SEND"
}

Message sent

After the content of the message has been prepared and the message is pushed to the Tall Bob system to the SMS (or email) gateway, this event is triggered.

ParameterTypeDescription
eventTypestringData category for this event
timestampintegerTimestamp in epoch time
eventIDstringID for this event
campaignIDstringID for the campaign
campaignNamestringName of the campaign
contactIDstringThe ID of the message recipient (Contact)
externalIDstring/nullYour unique ID for the recipient
recipientstringRecipient phone number (or email)
addressstring(Deprecated) Recipient phone number (or email)
statusstringMessage send status at above timestamp
referencestring/nullYour reference as provided in the API call when sending the message

Example Payload

{
"eventType": "message_pushed",
"timestamp": 1583377886,
"eventID": "018bfd96-5e8f-11ea-9281-0634275fc628",
"campaignID": "ed742e82-5e75-11ea-be99-061c79b2f7ce",
"campaignName": "webhooks",
"contactID": "8d38d7fc-daa9-11e9-bbe2-029c13ef7f22",
"recipient": "61411118802",
"address": "61411118802",
"status": "ACCEPTED",
"externalID": "AAA-111",
"reference": "BBB-222"
}

Message delivered

As messages are delivered to your recipients by the gateway, we receive delivery receipts (DLRs) that the message has been received (in the case of emails we are notified that the recipient mailbox has accepted the message) and this event is triggered.

ParameterTypeDescription
eventTypestringData category for this event
timestampintegerTimestamp in epoch time
eventIDstringID for this event
campaignIDstringID for the campaign
campaignNamestringName of the campaign
contactIDstringThe ID of the message recipient (Contact)
externalIDstring/nullYour unique ID for the recipient
recipientstringRecipient phone number (or email)
addressstring(Deprecated) Recipient phone number (or email)
statusstringMessage send status at above timestamp
referencestring/nullYour reference as provided in the API call when sending the message

Example Payload

{
"eventType": "message_delivered",
"timestamp": 1583377888,
"eventID": "0816d4b0-5e8f-11ea-a0b3-0634275fc628",
"campaignID": "ed742e82-5e75-11ea-be99-061c79b2f7ce",
"campaignName": "webhooks",
"contactID": "8d38d7fc-daa9-11e9-bbe2-029c13ef7f22",
"recipient": "61411118802",
"address": "61411118802",
"status": "DELIVERED",
"externalID": "AAA-111",
"reference": "BBB-222"
}

Delivery failed

If a message cannot be delivered to a recipient by the gateway, we are notified and this event is triggered.

ParameterTypeDescription
eventTypestringData category for this event
timestampintegerTimestamp in epoch time
eventIDstringID for this event
campaignIDstringID for the campaign
campaignNamestringName of the campaign
contactIDstringThe ID of the message recipient (Contact)
externalIDstring/nullYour unique ID for the recipient
recipientstringRecipient phone number (or email)
addressstring(Deprecated) Recipient phone number (or email)
statusstringMessage send status at above timestamp
referencestring/nullYour reference as provided in the API call when sending the message

Example Payload

{
"eventType": "message_delivery_error",
"timestamp": 1583377888,
"eventID": "0816d4b0-5e8f-11ea-a0b3-0634275fc628",
"campaignID": "ed742e82-5e75-11ea-be99-061c79b2f7ce",
"campaignName": "webhooks",
"contactID": "8d38dc52-daa9-11e9-9ef7-029c13ef7f22",
"recipient": "61455518802",
"address": "61455518802",
"status": "ENROUTE",
"externalID": "AAA-555",
"reference": "BBB-222"
}

SMS response received

When a recipient of an SMS message responds to a campaign that is utilising a subscribed long code, this event is triggered. Note that as new campaigns using the same long code are sent to the same recipients, their responses will be matched up against the most recent campaigns.

ParameterTypeDescription
eventTypestringData category for this event
timestampintegerTimestamp in epoch time
eventIDstringID for this event
campaignIDstringID for the campaign
campaignNamestringName of the campaign
recipientstringResponder’s phone number (recipient within the campaign)
addressstring(Deprecated) Recipient phone number (or email)
sentViastringLong code the response was sent to
messageTextstringText of the response
referencestring/nullYour reference as provided in the API call when sending the message

Example Payload

{
"eventType": "message_received",
"timestamp": 1583758504,
"eventID": "660768f2-6261-11ea-badd-0634275fc628",
"campaignID": "ed742e82-5e75-11ea-be99-061c79b2f7ce",
"campaignName": "webhooks",
"recipient": "61411118802",
"address": "61411118802",
"sentVia": "61429967196",
"messageText": "YES",
"reference": "BBB-222"
}

Inbound MMS received

When someone sends an MMS message to a subscribed long code, this event is triggered. Note that if any campaigns using the same long code have been sent to the sender, their inbound message will be matched up against the most recent of those campaigns.

ParameterTypeDescription
eventTypestringData category for this event
timestampintegerTimestamp in epoch time
eventIDstringID for this event
sentViastringLong code the incoming message was sent to
subjectstringMMS subject of the incoming message
fromstringSender’s phone number
contactIDstring/nullSender’s Contact ID (if the message was in response to a campaign)
campaignIDstring/nullID for the campaign (if any)
filesarrayList of files for the incoming MMS content. These links will be valid for 2 hours after the event is generated.

Example Payload

{
"eventType": "message_received",
"timestamp": 1598250748,
"eventID": "d4c72f86-5431-35fc-a328-61931b38bc84",
"campaignID": null,
"contactID": null,
"from": "61411118802",
"sentVia": "61429967196",
"subject": "screenshot attached",
"files": [
"https://example.com/4f3f5de2-5b71-349a-ac76-389249e8b364.png?authString=example"
]
}

Email Opened

Whenever someone opens an email from an email campaign, a notification is received and this event is triggered.

ParameterTypeDescription
eventTypestringData category for this event
timestampintegerTimestamp in epoch time
eventIDstringID for this event
campaignIDstringID for the campaign
campaignNamestringName of the campaign
contactIDstringThe ID of the message recipient (Contact)
externalIDstring/nullYour unique ID for the recipient
recipientstringRecipient email
addressstring(Deprecated) Recipient phone number (or email)
statusstringMessage send status at above timestamp

Example Payload

{
"eventType": "message_opened",
"timestamp": 1510630222,
"eventID": "9094553e-5e75-11e9-932f-029e1ef618c2",
"campaignID": "ff96b04e-5e8e-11ea-be28-061c79b2f7ce",
"campaignName": "email webhooks",
"contactID": "8d38dc52-daa9-11e9-9ef7-029c13ef7f22",
"recipient": "someone@example.com",
"address": "someone@example.com",
"status": "OPENED",
"externalID": "AAA-555"
}

Landing Page viewed

When a user clicks a link/thumbnail from a message and arrives at a Landing Page, the viewing of the page (also known as an “impression”) triggers this event.

ParameterTypeDescription
eventTypestringData category for this event
timestampintegerTimestamp in epoch time
eventIDstringID for this event
campaignIDstringID for the campaign
campaignNamestringName of the campaign
contactIDstringThe ID of the message recipient (Contact)
externalIDstring/nullYour unique ID for the recipient
videoIDstring/nullThe ID of the video used in the Landing Page (if any)
videoNamestring/nullName of the video
formIDstring/nullThe ID of the form used in the Landing Page (if any)
formNamestring/nullName of the form

Example Payload

{
"eventType": "impression",
"campaignID": "ed742e82-5e75-11ea-be99-061c79b2f7ce",
"timestamp": 1583337970,
"eventID": "45557b7a-5e8e-11ea-932f-029e1ef618c2",
"campaignName": "webhooks",
"contactID": "8d38d7fc-daa9-11e9-9ef7-029c13ef7f22",
"externalID": null,
"videoID": "5f222850-6fa1-11e9-8252-0617db59baea",
"videoName": "asteroid",
"formID": "af1267ae-a6b9-11e9-a4fe-0227e6a58070",
"formName": "thing that we need"
}

Contact clicked an ordinary link

While viewing a Landing Page, if an ordinary link (ie. not an unsubscribe link) is clicked on, this event is triggered.

ParameterTypeDescription
eventTypestringData category for this event
timestampintegerTimestamp in epoch time
eventIDstringID for this event
campaignIDstringID for the campaign
campaignNamestringName of the campaign
contactIDstringThe ID of the message recipient (Contact)
externalIDstring/nullYour unique ID for the recipient
videoIDstring/nullThe ID of the video used in the Landing Page (if any)
videoNamestring/nullName of the video
formIDstring/nullThe ID of the form used in the Landing Page (if any)
formNamestring/nullName of the form
IPstringThe IP address of the recipient
eventDetailsJSONdetails (URL) about the link that was clicked

Example Payload

{
"eventType": "clicktrack",
"campaignID": "ed742e82-5e75-11ea-be99-061c79b2f7ce",
"timestamp": 1583338096,
"IP": "123.123.123.123",
"eventID": "9094553e-5e8e-11ea-927f-029e1ef618c2",
"campaignName": "webhooks",
"contactID": "8d38d7fc-daa9-11e9-9ef7-029c13ef7f22",
"externalID": null,
"videoID": "5f222850-6fa1-11e9-8252-0617db59baea",
"videoName": "asteroid",
"formID": "af1267ae-a6b9-11e9-a4fe-0227e6a58070",
"formName": "thing that we need",
"eventDetails": {
"link": "https://tallbob.com"
}
}

Contact clicked an unsubscribe link

While viewing a Landing Page, if an unsubscribe link is clicked on, this event is triggered (and not the “ordinary” one).

ParameterTypeDescription
eventTypestringData category for this event
timestampintegerTimestamp in epoch time
eventIDstringID for this event
campaignIDstringID for the campaign
campaignNamestringName of the campaign
contactIDstringThe ID of the message recipient (Contact)
externalIDstring/nullYour unique ID for the recipient
videoIDstring/nullThe ID of the video used in the Landing Page (if any)
videoNamestring/nullName of the video
formIDstring/nullThe ID of the form used in the Landing Page (if any)
formNamestring/nullName of the form
IPstringThe IP address of the recipient

Example Payload

{
"eventType": "unsubscribe_track",
"campaignID": "ed742e82-5e75-11ea-be99-061c79b2f7ce",
"timestamp": 1583338199,
"IP": "123.123.123.123",
"eventID": "ce3b032e-5e8e-11ea-864a-029e1ef618c2",
"campaignName": "webhooks",
"contactID": "8d38d7fc-daa9-11e9-9ef7-029c13ef7f22",
"externalID": null,
"videoID": "5f222850-6fa1-11e9-8252-0617db59baea",
"videoName": "asteroid",
"formID": "af1267ae-a6b9-11e9-a4fe-0227e6a58070",
"formName": "thing that we need"
}

Contact opted out

After clicking through to an unsubscribe page (including clicking directly on any Opt-Out URL provided in the SMS message), if the user submits the form to register an Opt-Out, this event is triggered.

ParameterTypeDescription
eventTypestringData category for this event
timestampintegerTimestamp in epoch time
eventIDstringID for this event
campaignIDstringID for the campaign
campaignNamestringName of the campaign
contactIDstringThe ID of the message recipient (Contact)
externalIDstring/nullYour unique ID for the recipient
videoIDstring/nullThe ID of the video used in the Landing Page (if any)
videoNamestring/nullName of the video
formIDstring/nullThe ID of the form used in the Landing Page (if any)
formNamestring/nullName of the form
recipientstringThe recipient's phone number (or email) being unsubscribed
addressstring(Deprecated) Recipient phone number (or email)

Example Payload

{
"eventType": "unsubscribe",
"campaignID": "ed742e82-5e75-11ea-be99-061c79b2f7ce",
"timestamp": 1583338255,
"eventID": "af1267ae-daa9-9ef7-badd-029e1ef618c2",
"campaignName": "webhooks",
"contactID": "8d38d7fc-daa9-11e9-9ef7-029c13ef7f22",
"externalID": null,
"videoID": "5f222850-6fa1-11e9-8252-0617db59baea",
"videoName": "asteroid",
"formID": "af1267ae-a6b9-11e9-a4fe-0227e6a58070",
"formName": "thing that we need",
"recipient": "61412345678"
"address": "61412345678"
}

Video played

If a Landing Page contains a video, this event is triggered when someone clicks the Play button on the video player.

ParameterTypeDescription
eventTypestringData category for this event
timestampintegerTimestamp in epoch time
eventIDstringID for this event
campaignIDstringID for the campaign
campaignNamestringName of the campaign
contactIDstringThe ID of the message recipient (Contact)
externalIDstring/nullYour unique ID for the recipient
videoIDstring/nullThe ID of the video used in the Landing Page
videoNamestring/nullName of the video
formIDstring/nullThe ID of the form used in the Landing Page (if any)
formNamestring/nullName of the form
IPstringThe IP address of the recipient

Example Payload

{
"eventType": "video_play",
"campaignID": "ed742e82-5e75-11ea-be99-061c79b2f7ce",
"timestamp": 1583338012,
"IP": "123.123.123.123",
"eventID": "5e00a640-5e8e-11ea-9d74-029e1ef618c2",
"campaignName": "webhooks",
"contactID": "8d38d7fc-daa9-11e9-9ef7-029c13ef7f22",
"externalID": null,
"videoID": "5f222850-6fa1-11e9-8252-0617db59baea",
"videoName": "asteroid",
"formID": "af1267ae-a6b9-11e9-a4fe-0227e6a58070",
"formName": "thing that we need"
}

Video ended

This event is triggered when the player reaches the end of the video. If any content is skipped (as in Fast-Forwarded) the event will still fire, once the player has reached the end.

ParameterTypeDescription
eventTypestringData category for this event
timestampintegerTimestamp in epoch time
eventIDstringID for this event
campaignIDstringID for the campaign
campaignNamestringName of the campaign
contactIDstringThe ID of the message recipient (Contact)
externalIDstring/nullYour unique ID for the recipient
videoIDstring/nullThe ID of the video used in the Landing Page
videoNamestring/nullName of the video
formIDstring/nullThe ID of the form used in the Landing Page (if any)
formNamestring/nullName of the form
IPstringThe IP address of the recipient

Example Payload

{
"eventType": "video_complete",
"campaignID": "ed742e82-5e75-11ea-be99-061c79b2f7ce",
"timestamp": 1583338038,
"IP": "123.123.123.123",
"eventID": "6d09ef66-5e8e-11ea-a779-029e1ef618c2",
"campaignName": "webhooks",
"contactID": "8d38d7fc-daa9-11e9-9ef7-029c13ef7f22",
"externalID": null,
"videoID": "5f222850-6fa1-11e9-8252-0617db59baea",
"videoName": "asteroid",
"formID": "af1267ae-a6b9-11e9-a4fe-0227e6a58070",
"formName": "thing that we need"
}

Form submitted

If a Landing Page contains a form, this event is triggered when someone submits their responses to the form. If there are any logic/required fields on the form that block the submission, the event will not fire. Depending on the design of the form, multiple answers may exist for the same question.

ParameterTypeDescription
eventTypestringData category for this event
timestampintegerTimestamp in epoch time
eventIDstringID for this event
campaignIDstringID for the campaign
campaignNamestringName of the campaign
contactIDstringThe ID of the message recipient (Contact)
externalIDstring/nullYour unique ID for the recipient
videoIDstring/nullThe ID of the video used in the Landing Page (if any)
videoNamestring/nullName of the video
formIDstring/nullThe ID of the form used in the Landing Page
formNamestring/nullName of the form
IPstringThe IP address of the recipient
eventDetailsJSONdetails of the form responses, and the questions they correspond to

Example Payload

{
"eventType": "form_submission",
"campaignID": "ed742e82-5e75-11ea-be99-061c79b2f7ce",
"timestamp": 1583338052,
"IP": "123.123.123.123",
"eventID": "766f46c8-5e8e-11ea-ae97-029e1ef618c2",
"campaignName": "webhooks",
"contactID": "8d38d7fc-daa9-11e9-9ef7-029c13ef7f22",
"externalID": null,
"videoID": "5f222850-6fa1-11e9-8252-0617db59baea",
"videoName": "asteroid",
"formID": "af1267ae-a6b9-11e9-a4fe-0227e6a58070",
"formName": "thing that we need",
"eventDetails": [
{
"questionID": "af126d1c-a6b9-11e9-8d2d-0227e6a58070",
"questionText": "say something",
"value": "something",
"questionNumber": 1
}
]
}

Scratchie rendered

If a Landing Page contains a “Scratchie”, this event is triggered when that Scratchie has been rendered for the user, and is ready for interaction.

ParameterTypeDescription
eventTypestringData category for this event
timestampintegerTimestamp in epoch time
eventIDstringID for this event
campaignIDstringID for the campaign
campaignNamestringName of the campaign
contactIDstringThe ID of the message recipient (Contact)
externalIDstring/nullYour unique ID for the recipient
IPstringThe IP address of the recipient

Example Payload

{
"eventType": "scratchie_initiated",
"campaignID": "95ea5f9a-6287-11ea-a1ce-061c79b2f7ce",
"timestamp": 1583775010,
"IP": "123.123.123.123",
"eventID": "d5cafe1c-6287-11ea-b1e6-029e1ef618c2",
"campaignName": "scratch",
"contactID": "8d38d7fc-daa9-11e9-9ef7-029c13ef7f22",
"externalID": null
}

Scratchie interacted with

This event is triggered the first time a user has interacted with (ie “scratched”) the Scratchie on a Landing Page. They do not need to have completely removed the top layer for the event to fire; subsequent interactions by the same contact against the same Scratchie do not trigger additional events.

ParameterTypeDescription
eventTypestringData category for this event
timestampintegerTimestamp in epoch time
eventIDstringID for this event
campaignIDstringID for the campaign
campaignNamestringName of the campaign
contactIDstringThe ID of the message recipient (Contact)
externalIDstring/nullYour unique ID for the recipient
IPstringThe IP address of the recipient

Example Payload

{
"eventType": "scratchie_interact",
"campaignID": "95ea5f9a-6287-11ea-a1ce-061c79b2f7ce",
"timestamp": 1583775026,
"IP": "123.123.123.123",
"eventID": "df4177a0-6287-11ea-9cae-029e1ef618c2",
"campaignName": "scratch",
"contactID": "8d38d7fc-daa9-11e9-9ef7-029c13ef7f22",
"externalID": null
}

Helpful Stuff


  • Looking for definitions that revolve around the Mobile, SMS and Telco Industries, then click here
  • More information about Managing Webhooks can be found here
  • Other helpful developer documents can be found here

If you ever need further assistance or someone to point you in the right direction you can email the team at support@tallbob.com 

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select atleast one of the reasons

Feedback sent

We appreciate your effort and will try to fix the article