Web Hooks and Callbacks

Web Hooks and callbacks are used to handle asynchronous events in the DIY Surveys Platform. These refer to the following areas:

1. Messaging

2. Recipient upload and validation

3. Survey results collection

Messaging

When a message is sent it is possible to specify a callback method (or Web Hook) or use the one set up in your account as can be seen below:

This callback method is used when the following events occur:

1. The message has timed out.

2. The message has been sent.

3. The message delivery fails.

4. A carrier provides an update on the progress of the message, which also include a failure.

5. A tiny URL provided by DIY Surveys is clicked on in a message that was provided.

6. A recipient replies with the keywords STOP, HELP or INFO.

7. A recipient replies with an UNSTOP.

8. A recipient responds with a keyword that is owned by you.

9. A recipient responds and you were the last account to send a message to them.

10. The message was killed before it was sent.

11. There was no message to be killed. So it could have already been sent.

In each of these instances it is assumed that you have sent a message to that recipient. It is possible in your account to set up a call back URL which will always be used with the HTTP POST Method and provide a JSON response taking the following format:

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

The following describes the elements of the JSON:

Name	Description
Source	The source of the message. This can be a short code, a long number or a branded value up to 11 characters long.
Destination	The destination of the message. This must be the full number prefixed with the country code and no leading zeros.
Message	The text message to send. This can be up to 2000 characters long.
Type	The type of call back message. For more information see below.
Timestamp	When the call back message was created by the DIY Surveys Platform.
Inbound	A boolean value indicating that the call back refers to an inbound message and source reflects the destination you sent the message to and the destination represents where you sent it from.
Lookup	A boolean value indicating whether a lookup on the destination number should be carried out before it is sent to see whether the number is a landline or mobile. If the number is a landline it will not be sent. This combines the lookup method and the send into one process for you.
Test	A boolean value that indicates whether the message should be sent or not. If set to true the message will not be sent, but the internal DIY Surveys Routing will be tested.
Status	For more information on statuses check here.
MetaData	For more information on metadata check here.
MessageID	The DIY Surveys Message ID available for you to track the message in other methods and callbacks.
Carrier	The name of the carrier. This can be any valid string or the word Unknown
Reachable	A boolean value indicating whether the number is reachable.
NumberType	A string indicating the type of number - Mobile, Landline or Unknown

Callback Types

Type	Description
Receipt	An inbound message where the status reflects more information.
Lookup	A callback when the outbound message destination is check through the lookup service and fails.
Message	An inbound message that you will need to process.
Info	An inbound message that has been processed by DIY Surveys as an info message.
Help	An inbound message that has been processed by DIY Surveys as an help message.
Stop	A inbound message that has been detected as a STOP message from a recipient and has been added to the DIY Surveys STOP list.
Unstop	an inbound message that has been detected as an UNSTOP message from a recipient and gets removed from the DIY Surveys STOP list.
Keyword	An inbound message that has been processed by DIY Surveys as one of your keywords.
Click	A tiny URL was clicked on. In this instance the message includes the tiny URL that was clicked on.
Killed	The message has been killed before it was sent.
NotKilled	There was no message to be killed so it could have been sent.

Responding to Callbacks

Depending on the type of message depends on the type of response the DIY Surveys Platform expects.

Status Type Callbacks

For status type callbacks (Receipt, Lookup, Info, Help, Stop and Click) you can respond with an HTTP Success to complete the process. The DIY Surveys Platform will continue after any response and timeout within 30 seconds of sending the response. Any failures detected will be reported through the Fallback URL and/or email to you depending on your account setup.

Response Type Callbacks

For response type callbacks (Message, Keyword) the DIY Surveys Platform will wait for a response that includes a message to be sent to the recipient of the outbound message. This response will need to take the form of the Message/Send API method. In these instances the MessageID value will remain the same as the original message.

Handling Exceptions

The DIY Surveys Platform supports a number of exceptions to the normal process:

1. Timeout adjustment. You can set how long the DIY Surveys platform will wait before it gives up on a call back.

2. The number of times to try if there is a failure accessing a callback.

3. The action to take if a callback continues to fail. This can be an email (and/or SMS) alert which is sent to inform you the failure is taking place. DIY Surveys will be notified that this is happening and depending on the issue will respond through its normal support processes.

All these exceptions are managed either as additional parameters along with the callback reference in a call to the DIY Surveys API, or through your DIY Surveys Administration Account. If you use the your Account you can track the success or failure of recent calls to your callbacks saving you valuable time in debugging:

Note: If you do not use your account to set up callbacks then you do not access to the advanced logging.

Callback API Reference

Whilst is it possible to set up callbacks in your account you can also apply them in your API calls. The example below shows the parameters required to send a message with a callback reference:

URL: base/Message/Send
Method: POST
{
  "Source": "12345678901",
  "Destination": "12345678901",
  "Message": "message",
  "Reply": true,
  "When": "2020-02-04T11:47:33.645773+00:00",
  "Window": [{ From: "09:00", To: "16:00", Days: "1,2,3,4,5"}],
  "Callback": "https://yourco.com/api/messagetracker",
  "Lookup": true,
  "Test": false,
  "Timeout": "4320",
  "MetaData": 
    [
        { "RequestID": "1234567890DEFED" },
        { "OrgID": 1010 },
        { "Instance": "ETRERT"},
        { "Campaign": 1242 },
        { "TimeStamp": "2020-02-04T11:47:33.645773+00:00" }
    ]
}

Additional parameters can be added along with the Callback parameter in the following way:

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

Name	Description
Url	The callback Url. this can be an array of strings to support a list of Urls to attempt.
Timeout	For each attempt, what timeout period in milliseconds to use.
TotalTimeout	The total timeout to limit all attempts on all attempts.
Retries	The number of attempts to try the call back on an individual Url.
Action	The action to take. This can contain and/or SMS and Email as keywords. It requires an action list to be set up in your DIY Surveys Administration Account.
Method	The method to use with a callback Url. This can be either POST or GET. The default is POST.
ContentType	The content type to use with a callback Url. At the moment only application/json is supported.

DIY Surveys Administration Account

Your DIY Surveys Administration Account includes the same parameters that you can use in the API with the addition of a an email and/or SMS circulation list.

Security

All callbacks that are set up through your DIY Surveys Administration Account made to your platform will automatically follow the HMAC approach to security. This is not available just through the API becuase there is no way to share an AppId and Secret.

List

List web hooks for an account

URL: base/Webhook/List
Method: GET

Returns

[
    { "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
    },
    { ... }
]

Content Type

Content type can be a string from one of the following:

Name	Description
application/json	The content of the HTTP request will be supplied as JSON.
application/x-www-form-urlencoded	The content of the HTTP request will be supplied as a web form.

Type List

The type list is a string array that can contain one of the following:

Name	Description
Receipt	An inbound message where the status reflects more information.
Lookups	A callback when the outbound message destination is checked through the look up service and wit fails.
Message	An inbound message that you will need to process.
Info	An inbound message that has been processed by the platform as an info message.
Help	An inbound message that has been processed by the platform as a help message.
Stop	An inbound message that has been detected as a STOP message from a recipient and has been added to the global stop list.
Unstop	An inbound message that has been detected as an UNSTOP message from a recipient and has been removed from the global stop list.
Keyword	An inbound message that has been detected as one of your keywords.
Click	A tiny URL registered to you was clicked on.
Killed	The message has been killed before it was sent.
Not Killed	There was no message to be killed.
On Stop	The number being used is currently on stop.
Routing Failure	The message attempting to be sent could not be successfully routed.
Timed Out	The message attempted to be sent had timed out before it was processed.

Timeout Values

Name	Description
Timeout	For each attempt, what timeout period in milliseconds to use.
TotalTimeout	The total timeout to limit all attempts on all attempts.
Retries	The number of attempts to try the call back on an individual Url.

Status

The status refers to the HTTP status expected as a success response when the web hook is requested.