Callbacks / Web Hooks
Receiving notifications from Fonestorm
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
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
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
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
method
This parameter specifies the methods used for the callback and its data.
GET
returns data through query string parameters on aGET
to the given URL.POST
returns data through query string parameters on aPOST
to the given URL, with a full set of data in a JSON-encoded structure in the body. The request will have a header ofapplication/x-www-form-urlencoded
JSON
returns data through query string parameters on aPOST
to the given URL, with a full set of data in a JSON-encoded structure in the body. The request will have a header ofapplication/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
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
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
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
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"
}
Updated almost 5 years ago