Callbacks / Web Hooks

FoneStorm provides a standardized way of handling callbacks (also known as "web hooks"). These callbacks execute on selected events, like receiving a text message or making a phone call, and take the form of an HTTP(S) request to the given URL.

FoneStorm callbacks use a standardized set of parameter names for configuration, and a consistent way of responding. Not all callbacks offer all options, and the data available for the callback varies by the type of callback, so be sure to check the documentation for the specific callback to be used.

For performance reasons, FoneStorm only supports a single callback for each event. If you need to call multiple endpoints from a single event, it is suggested you set up a proxy to receive the FoneStorm callback, and distribute it to as many endpoints as needed.

General Configuration

type

The callback configuration can be set to None, 'Callback', or 'Email'. Using None will cancel any existing callbacks. Using Callback will result on a webhook being called to report the event, while using Email generates an email.

Email Configuration

email

If the type is set to Email, then this parameter containing the destination address will receive an email message containing event information in the body. Only a single email address is supported at this time.

Callback Configuration

url

The url parameter contains the URL to be called when the event takes place. The full URL, including the protocol (http:// or https://) needs to be provided. Tokens for data substitution can also be included; for more information see the Data Handling section

method

This parameter specifies the methods used for the callback and its data.

• GET returns data through query string parameters on a GET to the given URL.
• POST returns data through query string parameters on a POST to the given URL, with a full set of data in a JSON-encoded structure in the body. The request will have a header of application/x-www-form-urlencoded
• JSON returns data through query string parameters on a POST to the given URL, with a full set of data in a JSON-encoded structure in the body. The request will have a header of application/json

Not all methods are supported by all callbacks; any restrictions will be noted in the documentation for the specific callback.

For information on data encoding formats, see the Data Handling section.

url_username, url_password

FoneStorm callbacks support optional HTTP Basic authentication. If the url_username and url_password parameters are provided, the corresponding authentication headers will be included in callback execution.

Data Handling

Each type of url_method provides a different way of transmitting data associated with the callback. A full listing of available data and an explanation of their values is provided with the specific callback's documentation.

GET

If the method is GET, FoneStorm will apply token substitution to the value provided in url.

Example

If the url for a messages/receive_notify callback is https://my.example.com/notify.php?message=((msg)), the ((msg)) token will be replaced with the message that was received. The actual callback URL that is executed would be something like https://my.example.com/notify.php?message=hello%20world (assuming "hello world" was the message that was received).

POST

If the method is POST, FoneStorm will apply token substitutions to url, as with GET, but additionally it will provide the full set of available values in the body of the request, as JSON.

Example

If the url for a messages/receive_notify callback is https://my.example.com/notify.php, the body for the callback request will contain a string like {"to":"3215551212","from":"3215551111","message":"hello world","id":"0c4055acc5cc2736d818c96f4421b2f5"}.

JSON

If the method is JSON, FoneStorm will apply token substitutions to url, as with GET, but additionally it will provide the full set of available values in the body of the request, as JSON Object.

Example

If the url for a messages/receive_notify callback is https://my.example.com/notify.php, the body for the callback request will contain a JSON Object like

{
  "to":"3215551212",
  "from":"3215551111",
  "message":"hello world",
  "id":"0c4055acc5cc2736d818c96f4421b2f5"
}