Webhooks

Webhooks are application-specific HTTP/WebSocket endpoints that are used to trigger workflows. Webhooks are typically used to receive device data from external services.

Viewing Webhooks

You can view your application’s webhooks by clicking the Webhooks menu in the main application navigation.

Click a webhook’s name in the list to view its configuration, make edits, or view workflows associated with the webhook.

Creating a Webhook

Webhooks can be added to your application by using the Add Webhook button. The minimum configuration for a webhook is a name. Every webhook receives a unique, auto-generated, URL, which can be viewed after the webhook is created.

You also have the option to set the description, form of verification, and webhook reply options. More info on those is available below.

A unique URL is generated for every webhook and can found on the Edit Webhook screen, as well as in the list of webhooks.

Webhook Verification

For HTTP webhooks, WEGnology has built-in request verification for Amazon Alexa, Facebook Messenger, Fitbit, and Twilio. These services require a verification process that involves a handshake where the webhook must respond with a specific value in a specific format. If your service requires webhook verification and is not directly supported by WEGnology, it is possible to implement nearly any verification process in your workflow.

Verification codes are templatable from your application globals.

In the example above, the webhook is configured for Fitbit verification with the verification code set to VERIFICATION_CODE_HERE. The 204 response code cannot be changed since that’s the required code for the verification process.

No Verification

By default, webhooks are configured for no verification. The response code configured in this section is used as the default HTTP Status Code for this webhook’s responses. The default value is 200. This code can be overridden on a per-request basis when using Custom Replies.

Alexa

Alexa skills must verify that each request to the skill is from an Alexa-enabled device. This verification option ensures that each request to the webhook has valid headers Signature, SignatureCertChainUrl, and Timestamp. The timestamp must show the request is no older than 150 seconds. For more information on how to host a custom Alexa skill, please see Amazon’s documentation.

Facebook Messenger

For Facebook Messenger webhook verification, you provide Facebook a custom Verify Token. You must then provide that same token as the Verification Code in this section. Facebook then checks that these tokens match as a way to verify the webhook. You can read more about Facebook webhook verification in their documentation.

Fitbit

For Fitbit, you can find the verification code to use in the Subscriptions table for your Fitbit application. You can read more about Fitbit webhook verification in their documentation.

Twilio

Twilio does not actually require verification, but requires an empty TwiML XML response in order for Twilio not to consider it an error. Selecting the Twilio option instructs WEGnology to automatically reply with a properly formed response.

If there are other webhook verification systems that you would like WEGnology to support, please let us know.

Basic Authentication

You can optionally choose to require HTTP basic authentication on this webhook. For non-verified webhooks, adding basic authentication is the recommended way for securing access.

The username and password fields support templating from your application globals.

When the basic authentication fields are left blank, no authentication is required to invoke this webhook. If either a username or password value is provided, then a standard basic authentication HTTP header must be set on all incoming webhook requests. Configuring only a username or only a password is supported, in which case WEGnology expects the other field to be an empty string on incoming requests.

Custom Replies

Sometimes, it can be very useful to respond back to a given webhook call. In those cases, WEGnology offers the ability for workflows to reply to webhook triggers using the Webhook Reply Node. By default, webhooks do not wait for a reply to be generated by a workflow, so if you intend for a workflow to reply to a webhook trigger, the Wait for reply from workflow checkbox must be checked in the settings for that webhook.

When this checkbox is checked, any call against this webhook will generate a replyId which will be included in the payload for any workflows triggered by this webhook. WEGnology will wait up to 30 seconds for a reply to be created for this replyId using a Webhook Reply Node. If no reply is generated, the webhook will respond with a timeout error. If multiple replies are generated, the first reply will be the one used. See the documentation for the Webhook Reply Node for more details.

Deleting a Webhook

Webhooks can be deleted by clicking the Delete icon on the webhook list or by clicking the Delete Webhook button on the details screen.

When deleting a webhook, you also have the option to delete any workflows triggered by the webhook. This action deletes any workflow with a Webhook Trigger Node matching this webhook. If you wish to save your workflows and change out their triggers, or if the workflows are triggered by multiple conditions and you wish to retain them, you should leave this option unchecked.

Using Webhooks

For information on how to use Webhooks to trigger workflows see the Webhook Trigger Node documentation.

Testing Webhooks

You can trigger an HTTP webhook for testing purposes by selecting the Test tab on the webhook’s details page.

In the example above, you can fill in an optional path with query params, choose the request method, and the body (if provided) must be valid JSON. Clicking Send Test Request will trigger the Webhook just like an actual request against that Webhook’s URL would.

Webhook Throttling

Webhook requests are limited to 100 calls in a 10-second window (or, on average, 10 per second) per webhook. For WebSockets, each client connection and message sent from a client to the platform counts towards this limit. WebSocket messages sent from the platform to clients do not count towards this limit.

If this limit is exceeded, the webhook will respond with a 429 “Over rate limit, request throttled” error. If this limit is exceeded due to WebSocket messages, the WebSocket connection will be closed.

Webhooks are also limited to 100 concurrent connections per webhook. If a connection is attempted and the webhook is at its concurrency limit, the client will receive a 429 error.

HTTP requests and WebSocket messages are both limited to a maximum payload size of 256KB. If an HTTP request exceeds the payload limit, the client will receive a 413 (content too large) error. If a WebSocket message exceeds the payload limit, the client will be disconnected with a 1008 (policy violation) error.