Webhook Formats

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.

Webhook Data Definitions

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

• A message prepared for delivery
• Message sent
• Message delivered 
• Delivery failed
• SMS response received
• Inbound MMS received
• Email Opened
• Landing Page viewed
• Contact clicked an ordinary link
• Contact clicked an unsubscribe link
• Contact opted out
• Recipient clicked a shortened URL
• Video played
• Video ended
• Form submitted
• Scratchie rendered
• Scratchie interacted with

A message prepared for delivery [Event Type - message_ polling]

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.

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 [Event Type - message_ pushed]

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.

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 [Event Type - 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.

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 [Event Type - message_delivery_error]

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

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[Event Type - message_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.

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 [Event Type - message_received_mms]

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.

Example Payload

{
    "eventType": "message_received_mms",
    "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 [Event Type - message_opened]

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

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 [Event Type - impression]

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.

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 [Event Type - clicktrack]

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

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 [Event Type - unsubscribe_track]

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

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 [Event Type - unsubscribe]

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.

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"
}

Recipient clicked a Shortened Link [Event Type - shortened_url_hit]

When a recipient receives a message that has a link shortened by our URL shortening system, this event is triggered.

Example Payload

{
    "eventType": "shortened_url_hit",
    "campaignID": "ed742e82-5e75-11ea-be99-061c79b2f7ce",
    "timestamp": 1583338096,
    "IP": "123.123.123.123",
    "eventID": "9094553e-5e8e-11ea-927f-029e1ef618c2",
    "campaignName": "url demo",
    "recipient": "61412345678",
    "address": "61412345678",
    "reference": "BBB-222",
    "eventDetails": {
        "link": "https://tallbob.com"
    }
}

Video played [Event Type - video_play]

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

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 [Event Type - video_complete]

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.

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 [Event Type - form_submission]

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.

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 [Event Type - scratchie_initiated]

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.

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 [Event Type - scratchie_interact]

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.

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
}