Web Hooks and Callbacks

Web hooks and callbacks handle asynchronous events in the DIY Surveys platform.

They apply to:

1. Messaging.
2. Recipient upload and validation.
3. Survey results collection.

Messaging

When a message is sent, you can specify a callback method or use the one configured in your account.

Callback events include:

1. The message has timed out.
2. The message has been sent.
3. Message delivery failed.
4. A carrier provides a progress update, including failure.
5. A DIY Surveys TinyUrl is clicked.
6. A recipient replies with STOP, HELP, or INFO.
7. A recipient replies with UNSTOP.
8. A recipient responds with one of your keywords.
9. A recipient responds and you were the last account to send them a message.
10. The message was killed before it was sent.
11. There was no message to kill, so it may already have been sent.

Callback payloads are sent using HTTP POST and JSON.

Callback payload fields

Name	Description
Source	Source of the message: short code, long number, or branded value up to 11 characters.
Destination	Full destination number, country-code prefixed, with no leading zeros.
Message	Text message, up to 2000 characters.
Type	Callback message type.
Timestamp	When the callback was created by the platform.
Inbound	Indicates an inbound message.
Lookup	Indicates whether a lookup on the destination number should occur before sending.
Test	If true, the message is not sent but internal routing is tested.
Status	Message status.
MetaData	Metadata associated with the message.
MessageID	DIY Surveys message ID.
Carrier	Carrier name, or Unknown.
Reachable	Whether the number is reachable.
NumberType	Mobile, Landline, or Unknown.

Example callback:

{
  "Source": "12345678901",
  "Destination": "12345678901",
  "Message": "message",
  "Type": "receipt",
  "Timestamp": "2020-02-04T11:47:33.645773+00:00",
  "Inbound": true,
  "Lookup": true,
  "Test": false,
  "Status": "sent",
  "Segments": 1,
  "MetaData": [
    { "RequestID": "1234567890DEFED" },
    { "OrgID": 1010 },
    { "Instance": "ETRERT" },
    { "Campaign": 1242 },
    { "TimeStamp": "2020-02-04T11:47:33.645773+00:00" }
  ],
  "MessageID": "MS1312312312323",
  "Carrier": "EE",
  "Reachable": true,
  "NumberType": "Mobile"
}

Callback types

Type	Description
Receipt	Inbound message where status reflects more information.
Lookup	Callback when an outbound destination check fails.
Message	Inbound message that your platform needs to process.
Info	Inbound message processed by DIY Surveys as an info message.
Help	Inbound message processed by DIY Surveys as a help message.
Stop	STOP message detected and added to the DIY Surveys STOP list.
Unstop	UNSTOP message detected and removed from the DIY Surveys STOP list.
Keyword	Inbound message processed as one of your keywords.
Click	TinyUrl click event.
Killed	Message killed before sending.
NotKilled	No message was killed because it may already have been sent.

Responding to callbacks

Status type callbacks

For status callbacks such as Receipt, Lookup, Info, Help, Stop, and Click, return HTTP success to complete the process. DIY Surveys continues after any response and times out within 30 seconds.

Response type callbacks

For Message and Keyword callbacks, the platform waits for a response that includes a message to send to the recipient. This response should take the form of the Message/Send API method. The MessageID remains the same as the original message.

Handling exceptions

DIY Surveys supports:

1. Callback timeout adjustment.
2. Retry count configuration.
3. Failure action configuration, such as email and/or SMS alerts.

These can be configured as callback parameters in API calls or through the DIY Surveys Administration Account.

Callback API reference

Callback parameters can be supplied with Callback:

Name	Description
Url	Callback URL. Can be an array of strings for fallback attempts.
Timeout	Timeout period in milliseconds for each attempt.
TotalTimeout	Total timeout across attempts.
Retries	Number of attempts on an individual URL.
Action	Action to take, using keywords such as Email and Sms.
Method	POST or GET. Default is POST.
ContentType	Currently only application/json is supported.

Example callback parameter block:

"Callback": [
  { "Url": "https://yourco.com/api/messagetracker" },
  { "Timeout": 2000 },
  { "TotalTimeout": 30000 },
  { "Retries": 10 },
  { "Action": "Email,Sms" },
  { "Method": "POST" },
  { "ContentType": "application/json" }
]

Administration account

The DIY Surveys Administration Account includes the same parameters plus email and/or SMS circulation lists.

Security

Callbacks configured through the DIY Surveys Administration Account automatically follow the HMAC security approach. This is not available solely through the API because there is no way to share an AppId and Secret through that route.

List

Lists web hooks for an account.

URL: base/Webhook/List
Method: GET

Example response:

[
  {
    "Name": "Name",
    "Key": "Key",
    "Secret": "Secret",
    "Payload": "http://example.payload.com/api/webhook",
    "ContentType": "application/json",
    "IsActive": "true",
    "TypeList": ["All"],
    "Method": "POST",
    "Timeout": 30000,
    "TotalTimeout": 30000,
    "Retries": 1,
    "Status": 200
  }
]