Webhook channel overview
Learn more about how to use Knock webhook channels to send to custom destinations, build reusable fetch steps, and to power customer-facing webhooks within your own product.
Features and use cases
You can use the Knock webhook channel type to build a custom channel that sends a webhook request to a configured endpoint. This endpoint can be static, or can be dynamically built using liquid variables during workflow run time. The Knock webhook channel supports PUT, POST, and GET requests, making it a flexible tool to use for a number of different use cases.
You might use the Knock webhook channel to...
- Configure a custom channel (examples: PagerDuty, a proprietary in-house service) that you want to send a request to as part of your Knock workflow
- Codify commonly used fetch requests (such as fetching information about a user) for use across your different Knock workflows
- Build user-facing, configurable webhooks into your own product so your users can receive a webhook when something happens in your product
In this overview, we'll cover how to configure webhook channels in Knock and use them in your notification workflows.
Create and configure your webhook channel
To create your webhook channel, go to the Knock dashboard and navigate to Integrations > Channels. Click "Create channel", select the Webhook channel type, and click "Next".
Provide a name, key, and description for your webhook channel.
Note: the name and description provided will be used in the workflow builder on steps that use this webhook channel, so be as descriptive as possible so other members of your account know how to use your webhook channel.
Once your webhook channel has been created, you'll be able to manage its configuration on a per-environment basis. As with all Knock channels, webhooks can be used in sandbox mode and can be used with channel conditions.
You'll also need to build the actual webhook request that you want your webhook channel to send when it's triggered within a Knock workflow. We cover this topic in the next section.
Build your webhook request
To start building your webhook request, navigate to your webhook channel and click "Edit webhook".
You'll now be looking at the webhook channel configuration page. The webhook channel behaves just like our fetch function, it sends a request to the endpoint you define with the headers, params, and body payload you provide.
To learn how to build a webhook request in detail, you can read our fetch function documentation.
As an example if you want to build a webhook that will always fetch the recipient's user information, you'd build the following URL to dynamically call the endpoint based on the active workflow run's recipient ID: https://foobar/com/api/users/{{ recipient.id }}
Use your webhook channel
Once your webhook channel is configured and you've built its webhook request, you're ready to add your webhook channel to a workflow.
Webhook channels are added to Knock workflows the same way as any other channel. Just go to the Knock workflow builder and add your webhook step.
Overriding webhook configurations
When you add your webhook channel to a workflow, by default it will use the webhook request you built in your channel. You can override this as you see fit on a per-step basis. If at any time you want to reset a webhook step back to its channel default, just click "Reset to default channel settings".
Securing your webhooks
The webhook channel offers request signing as a setting on the channel. When request signing is enabled, Knock will generate a signing key and use that to sign the request in a x-webhook-signature header that can be verified by the consumer.
Request signing is enabled per-environment configuration of the webhook channel under the "Manage configuration" modal. Once request signing is enabled, Knock will generate a signing key for you to verify the signature against. This key can be configured to be any value, or even a dynamic value resolved from the workflow run scope if necessary (see below for more).
Using a dynamic signing key
In some cases, you may wish to use a dynamic signing key to verify your webhooks. For example, if you're using the webhook channel to power customer-configurable webhooks, you may want a different signing key per webhook configuration.
You can add a dynamic signing key by using liquid in the signing key input field. For example, if your signing key was stored on an object that represented the webhook you can reference the key as {{ recipient.webhook_signing_key }}.
Note: if the signing key is empty the webhook request will be skipped.
Verifying the signature
The signature is generated with an HMAC using the SHA256 algorithm and, before being encoded, is comprised of the timestamp and the stringified JSON payload of the request. We encode "timestamp in numerical form"."stringified payload" as the signature of the request.
The x-webhook-signature header is a string comprised of the timestamp used in the encoding and the encoded value above. It will look like this: t=timestamp,s=encoded-signature
To test that the payload sent has not been compromised, you can recreate the signature using the signing key found on the webhook channel configuration and compare it to the one sent in the header.
-
Split the
x-webhook-signatureon the comma (",") and extract the values of timestamp and signature. -
Construct the value of the signature by concatenating:
- The timestamp (as a string)
- The character
. - The stringified JSON payload
-
Generate the signature with an HMAC and SHA256 algorithm using the signing key from your webhook's channel configuration.
-
Compare your generated signature with the one extracted in step one; they should match exactly. If the timestamp is more than five minutes old compared to the current time, you may decide you want to reject the payload for additional security.