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
- Message sent
- Message delivered
- Delivery failed
- SMS response received
- Inbound MMS received
- Email opened
- Landing Page viewed
- Contact clicked ordinary link
- Contact clicked unsubscribe link
- Contact opted out
- Video played
- Video ended
- Form submitted
- Scratchie rendered
- Scratchie interacted with
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 }