Webhooks - or the bttn HTTP action like we call it - provide a simple way to trigger your
server processes. When the bttn is pressed the bt.tn server makes a HTTP request to the
bttn's webhook URL. If the request completes with a HTTP status code indicating success
(HTTP status code 200 - 299), then the bttn leds flash green. Otherwise they
flash red to indicate failure.
There are two ways to set the webhook URL for the bttn HTTP action:
The HTTP action supports the GET, POST and PUT HTTP methods.
Arguments can be specified in application/x-www-form-urlencoded or
application/json formats. You can use special tags in the argument data. When the HTTP
action is executed these tags are replaced with their runtime values. This way you can easily pass
dynamic data such as times and dates in the webhook requests. Read more about
using tags here.
You can also specify custom HTTP headers to convey Api-Keys, access tokens and other data.
The HTTP action supports HTTPS with server side certificates. If your server is using self-signed certificates, then you need to disable server certificate validation, but you can still use HTTPS for encryption.
HTTP basic and digest authentication methods are supported.
When the bt.tn server performs the HTTP request, it expects that the response is received immediately, typically within about 10 seconds. This is because we want the HTTP action to fail fast and signal the bttn device whenever there are problems in the network connectivity.
In some cases your server may need more time to complete the HTTP request. For this purpose the bttn HTTP action supports an asynchronous mode.
In the asynchronous mode the bt.tn server generates a unique HTTP callback URL and passes it to your server in the HTTP request. Your server can then store the HTTP request data, complete the request towards the bt.tn server and start processing the task in the background. When the task is completed, your server passes the result back to bt.tn server by making a HTTP request to the HTTP callback URL.
The asynchronous mode allows your server to perform time consuming tasks without binding bt.tn server resources and still keeping the bttn devices responsive.
Learn more about the asynchronous HTTP action here.
You can use RequestBin to quickly see the result of your HTTP action.
Visit http://requestb.in/ and click "Create a RequestBin". Copy the Bin URL to your clipboard but keep the Bin page open.
Log into my.bt.tn in another browser window, select the bttn you want to test & click "Set Action". This is the small bolt button next to the bttn name.
Click on the "New Action" icon.
On the "Set Action" page, select "Execute action if bttn is pressed", then "Next".
Select "HTTP" as the type of message you want to send, then press "Next".
Select "Specify URL" and paste the Bin URL into the text box below. Set HTTP method to
"GET". "Argument format" can be set to
application/x-www-form-urlencoded and KEY & VALUE can be both set to
"test".
Finally, scroll to the bottom and press "Submit". You'll see a confirmation dialog, where you need to press "Save".
Press the bttn.
Reload the RequestBin page to see the web hook request.