Webhooks

We've built Webhooks in Fostrom so that you can trigger them from your Actions. The idea is to have incoming messages trigger Actions when certain real-world events happen on your devices, and subsequently trigger Webhooks from those Actions to communicate with external systems. You can use it to, for example, send a notification to a Discord channel, or to your own external systems which can do something based on a webhook call.

The webhooks infrastructure is already quite reliable, and will retry the queued webhooks in case your endpoint is unreachable or returns a non 200-range status code.

Webhooks don't have a separate top-level tab unlike the other resources. They're located in your Fleet Settings.

Creating a Webhook

To create a webhook, go to your Fleet Settings, click on the Webhooks tab, and then click on the New Webhook button. You'll need to enter a name, the URL of your webhook (needs to start with https://), the HTTP method (the default is POST), and the HTTP Header value for Content-Type, which can either be JSON or Plain Text. You should also enter a description detailing what the webhook is for.

If you choose Plain Text, the body will be a string. If you choose JSON, the body will be the JSON object or array that you provide in the Action.

There are exceptions to this though. Discord needs an object containing your string message. So if you put a Discord URL, we'll correctly handle it. We're also going to add support for Slack webhooks soon. Note that Discord requires a query parameter ?wait=true to return a 200 OK status code. Otherwise it does not return any response, which our system assumes is a failure. We add that parameter automatically.

However, if your own Webhook listener does not return 200 OK, that might be a problem as we retry the webhook call. Test the Webhook URL yourself and ensure that it returns a 200 OK response.

You can change any aspect of the webhook later.

Triggering a Webhook

To trigger a Webhook from an Action, you can simply write:

fostrom.triggerWebhook(<select-webhook-from-autocomplete>,
  {body: "params"} || "plain text string"
)

It is important that you select the webhook you need from the autocomplete, as writing the name in a string won't work. Behind the scenes, we use the Webhook ID to keep everything working correctly.

The second parameter to the function needs to be either an object or a string, depending on your chosen Content-Type. If you are using a Discord webhook, provide a string.