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.

Webhook Type

Webhooks support both traditional HTTP requests and persistent WebSocket connections, though only one request type at a time. When creating a webhook, you must choose which type of request the webhook should support, and depending on the chosen type, additional configuration is required.

• HTTP is the most common type. When a webhook is configured for HTTP, your workflow is triggered for each request. When choosing HTTP, you must also configure the following …

  • If you are expecting binary data to be submitted in webhook requests, set the Cast Binary Buffers As … option to one of the following …

    • Integer Array
    • Binary String
    • UTF-8 String (default)
    • Base64 String
    • Hex String
  • If you are expecting multipart file uploads through the webhook, enable the Annotate Multipart File Uploads option to have WEGnology automatically parse and include meta information about the file(s) - such as the file name and content-type - in the request payload.
  • Whether the webhook response should serve Custom Replies, as described below.
  • Whether the request requires Verification, as described below.
• When configured for WebSocket requests, any Webhook Triggers for the webhook are triggered whenever a client connects, sends data, or disconnects. The resulting workflow payload contains a type field to distinguish between these events. In most cases, clients will send multiple data messages between connecting and disconnecting. See the Webhook Trigger documentation for full payload details.

Custom Replies

By default, WEGnology automatically replies to HTTP webhook requests with the body { "success" : true } and the status code specified in the Verification section.

If your use case requires a custom reply, this can be done by enabling the Wait for reply from workflow checkbox. When this option is enabled, you must use a Webhook Reply Node within your workflow to provide the desired body, status code, and any reply headers.

If this option is enabled and your workflow(s) never replies, the request will time out after 60 seconds and WEGnology will automatically reply with a 504 status code and the following body:

{ "error": "Time out waiting for workflow reply" }

If your workflow(s) reply to the same HTTP webhook request multiple times, the first reply will be used and all subsquent replies are ignored.

The Wait for reply from workflow option does not apply to WebSocket webhooks. WebSockets are persistent and bidirectional connections. Unlike HTTP, which has a request/response model, WebSocket messages can flow in either direction and messages do not require responses. Therefore, all WebSocket webhooks automatically support the ability to send messages to connected clients using the Webhook Reply Node. Also, unlike HTTP webhooks, you can invoke a Webhook Reply Node as many times as you want for the same connection. Each invocation results in a WebSocket message being sent to the client (identified by its unique replyId) and the underlying connection remains open.

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.

Meta

Webhook requests from Meta services - such as Messenger, WhatsApp, and more - require you to provide a custom Verify Token. You must then provide that same token as the Verification Code in this section. Meta then checks that these tokens match as a way to verify the webhook. You can read more about 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, regardless of the chosen type. 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.

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 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 documentation.

Testing Webhooks

You can trigger an HTTP webhook for testing purposes by selecting the Test tab on the webhook’s details page. WebSocket webhooks cannot be tested through the interface.

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.