> For the complete documentation index, see [llms.txt](https://apidocs.diysurveys.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.diysurveys.com/callbacks.md).

# 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:

<figure><img src="/files/ylV8FfAtp6F9GAXLpsIT" alt=""><figcaption></figcaption></figure>

This callback method is used when the following events occur:

1. The message has timed out.&#x20;
2. The message has been sent.&#x20;
3. The message delivery fails.&#x20;
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`.&#x20;
7. A recipient replies with an `UNSTOP`.&#x20;
8. A recipient responds with a keyword that is owned by you.&#x20;
9. A recipient responds and you were the last account to send a message to them.&#x20;
10. The message was killed before it was sent.&#x20;
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](/message/messagestatuses.md).                                                                                                                                                                                                              |
| MetaData    | For more information on metadata check [here](/message/metadata.md).                                                                                                                                                                                                                     |
| 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](/message/messagestatuses.md) 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](/message.md). 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:&#x20;

1. Timeout adjustment. You can set how long the DIY Surveys platform will wait before it gives up on a call back.&#x20;
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:

![](/files/-MkaxFBJwmT_28ObVdw_)

> 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](/security.md). This is not available just through the API becuase there is no way to share an AppId and Secret.

## List&#x20;

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:

<table><thead><tr><th width="293">Name</th><th>Description</th></tr></thead><tbody><tr><td>application/json</td><td>The content of the HTTP request will be supplied as JSON.</td></tr><tr><td>application/x-www-form-urlencoded</td><td>The content of the HTTP request will be supplied as a web form.</td></tr></tbody></table>

### Type List

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

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

### Timeout Values

<table data-header-hidden><thead><tr><th width="203">Name</th><th>Description</th></tr></thead><tbody><tr><td>Name</td><td>Description</td></tr><tr><td>Timeout</td><td>For each attempt, what timeout period in milliseconds to use.</td></tr><tr><td>TotalTimeout</td><td>The total timeout to limit all attempts on all attempts.</td></tr><tr><td>Retries</td><td>The number of attempts to try the call back on an individual Url.</td></tr></tbody></table>

### Status

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://apidocs.diysurveys.com/callbacks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.