Webhook Formats

Every webhook request is a standard POST request with a JSON-encoded payload which 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 VidCorp handles your webhook URL being unable to accept requests.

Note

Changes which 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.

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.

Parameter Type Description
eventType string Data category for this event
timestamp integer Timestamp in epoch time
eventID string ID for this event
campaignID string ID for the campaign
campaignName string Name of the campaign
contactID string ID of the message recipient (Contact)
recipient string Recipient phone number (or email)
address string (Deprecated) Recipient phone number (or email)
status string Message 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 message content has been prepared and the message is pushed to the VidCorp system to the SMS (or email) gateway, this event is triggered.

Parameter Type Description
eventType string Data category for this event
timestamp integer Timestamp in epoch time
eventID string ID for this event
campaignID string ID for the campaign
campaignName string Name of the campaign
contactID string ID of the message recipient (Contact)
externalID string / null Your unique ID for the recipient
recipient string Recipient phone number (or email)
address string (Deprecated) Recipient phone number (or email)
status string Message send status at above timestamp
reference string / null Your reference 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.

Parameter Type Description
eventType string Data category for this event
timestamp integer Timestamp in epoch time
eventID string ID for this event
campaignID string ID for the campaign
campaignName string Name of the campaign
contactID string ID of the message recipient (Contact)
externalID string / null Your unique ID for the recipient
recipient string Recipient phone number (or email)
address string (Deprecated) Recipient phone number (or email)
status string Message send status at above timestamp
reference string / null Your reference 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.

Parameter Type Description
eventType string Data category for this event
timestamp integer Timestamp in epoch time
eventID string ID for this event
campaignID string ID for the campaign
campaignName string Name of the campaign
contactID string ID of the message recipient (Contact)
externalID string / null Your unique ID for the recipient
recipient string Recipient phone number (or email)
address string (Deprecated) Recipient phone number (or email)
status string Message send status at above timestamp
reference string / null Your reference 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 back 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.

Parameter Type Description
eventType string Data category for this event
timestamp integer Timestamp in epoch time
eventID string ID for this event
campaignID string ID for the campaign
campaignName string Name of the campaign
recipient string Responder’s phone number (recipient within the campaign)
address string (Deprecated) Recipient phone number (or email)
sentVia string Long code the response was sent to
messageText string Text of the response
reference string / null Your reference 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.

Parameter Type Description
eventType string Data category for this event
timestamp integer Timestamp in epoch time
eventID string ID for this event
sentVia string Long code the incoming message was sent to
subject string MMS subject of the incoming message
from string Sender’s phone number
contactID string / null Sender’s Contact ID (if message was in response to a campaign)
campaignID string / null ID for the campaign (if any)
files array List 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.

Parameter Type Description
eventType string Data category for this event
timestamp integer Timestamp in epoch time
eventID string ID for this event
campaignID string ID for the campaign
campaignName string Name of the campaign
contactID string ID of the message recipient (Contact)
externalID string / null Your unique ID for the recipient
recipient string Recipient email
address string (Deprecated) Recipient phone number (or email)
status string Message 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.

Parameter Type Description
eventType string Data category for this event
timestamp integer Timestamp in epoch time
eventID string ID for this event
campaignID string ID for the campaign
campaignName string Name of the campaign
contactID string ID of the message recipient (Contact)
externalID string / null Your unique ID for the recipient
videoID string / null ID of the video used in the Landing Page (if any)
videoName string / null Name of the video
formID string / null ID of the form used in the Landing Page (if any)
formName string / null Name 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 ordinary link

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

Parameter Type Description
eventType string Data category for this event
timestamp integer Timestamp in epoch time
eventID string ID for this event
campaignID string ID for the campaign
campaignName string Name of the campaign
contactID string ID of the message recipient (Contact)
externalID string / null Your unique ID for the recipient
videoID string / null ID of the video used in the Landing Page (if any)
videoName string / null Name of the video
formID string / null ID of the form used in the Landing Page (if any)
formName string / null Name of the form
IP string IP address of user
eventDetails json details (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://vidcorp.com"
    }
}

Contact clicked unsubscribe link

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

Parameter Type Description
eventType string Data category for this event
timestamp integer Timestamp in epoch time
eventID string ID for this event
campaignID string ID for the campaign
campaignName string Name of the campaign
contactID string ID of the message recipient (Contact)
externalID string / null Your unique ID for the recipient
videoID string / null ID of the video used in the Landing Page (if any)
videoName string / null Name of the video
formID string / null ID of the form used in the Landing Page (if any)
formName string / null Name of the form
IP string IP address of user

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 and opts-out, this event is triggered.

Parameter Type Description
eventType string Data category for this event
timestamp integer Timestamp in epoch time
eventID string ID for this event
campaignID string ID for the campaign
campaignName string Name of the campaign
contactID string ID of the message recipient (Contact)
externalID string / null Your unique ID for the recipient
videoID string / null ID of the video used in the Landing Page (if any)
videoName string / null Name of the video
formID string / null ID of the form used in the Landing Page (if any)
formName string / null Name of the form
recipient string Recipient phone number (or email) being unsubscribed
address string (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.

Parameter Type Description
eventType string Data category for this event
timestamp integer Timestamp in epoch time
eventID string ID for this event
campaignID string ID for the campaign
campaignName string Name of the campaign
contactID string ID of the message recipient (Contact)
externalID string / null Your unique ID for the recipient
videoID string / null ID of the video used in the Landing Page
videoName string / null Name of the video
formID string / null ID of the form used in the Landing Page (if any)
formName string / null Name of the form
IP string IP address of user

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.

Parameter Type Description
eventType string Data category for this event
timestamp integer Timestamp in epoch time
eventID string ID for this event
campaignID string ID for the campaign
campaignName string Name of the campaign
contactID string ID of the message recipient (Contact)
externalID string / null Your unique ID for the recipient
videoID string / null ID of the video used in the Landing Page
videoName string / null Name of the video
formID string / null ID of the form used in the Landing Page (if any)
formName string / null Name of the form
IP string IP address of user

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 is 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.

Parameter Type Description
eventType string Data category for this event
timestamp integer Timestamp in epoch time
eventID string ID for this event
campaignID string ID for the campaign
campaignName string Name of the campaign
contactID string ID of the message recipient (Contact)
externalID string / null Your unique ID for the recipient
videoID string / null ID of the video used in the Landing Page (if any)
videoName string / null Name of the video
formID string / null ID of the form used in the Landing Page
formName string / null Name of the form
IP string IP address of user
eventDetails json details 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, ready for interaction.

Parameter Type Description
eventType string Data category for this event
timestamp integer Timestamp in epoch time
eventID string ID for this event
campaignID string ID for the campaign
campaignName string Name of the campaign
contactID string ID of the message recipient (Contact)
externalID string / null Your unique ID for the recipient
IP string IP address of user

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.

Parameter Type Description
eventType string Data category for this event
timestamp integer Timestamp in epoch time
eventID string ID for this event
campaignID string ID for the campaign
campaignName string Name of the campaign
contactID string ID of the message recipient (Contact)
externalID string / null Your unique ID for the recipient
IP string IP address of user

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
}