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.

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 GET, POST, PUT, DELETE, and PATCH 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.

To create your webhook channel, go to the Knock dashboard and navigate to Channels and sources in your account settings. Click "Create channel," select the Webhook channel type, and click "Next."

Provide a name, key, and description for 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.

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. You build a webhook request the same way you build a fetch function request: you define the endpoint, method, headers, params, and body payload, and you can use liquid in each of those fields.

To learn how to build a webhook request in detail, you can read our fetch function documentation.

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.

When you add your webhook channel to a workflow, it will use the webhook request you built in your channel configuration by default. You can override this on a per-step basis.

Editing a webhook step's template, such as changing the URL or body, creates 'channel setting overrides,' replacing the default environment settings with your changes. Any template modifications will include the entire template (URL, headers, params, and body) in the overrides. These overrides apply to all environments where the step is promoted.

To reset a webhook step to its channel default, click "Reset to default channel settings."

Knock treats any webhook channel response outside the 2xx range, along with connection errors and timeouts, as a failed send. Knock waits up to 50 seconds for a response before treating the request as a timeout.

Most failures are retried according to the retry logic documented here, for a maximum of 8 attempts. Webhook channel sends use a small list of statuses that indicate a request will never succeed; everything else is considered retryable.

Knock will not retry a webhook send when your endpoint responds with:

Status	Meaning
401	Unauthorized
403	Forbidden
404	Not found
405	Method not allowed

Knock also fails without retrying when it cannot build or issue the request at all. These cases include a malformed URL, a URL that uses a scheme other than https, and a hostname that does not resolve.

In each of these cases, the message's delivery status moves to undelivered after the first attempt. Read more about message delivery statuses here.

Every other failure is retried, including:

• Client errors. 4xx-status responses other than those listed above, most notably 400 Bad Request, 409 Conflict, 422 Unprocessable Entity, and 429 Too Many Requests.
• Server errors. Any 5xx level HTTP status code.
• Redirects. Any 3xx level HTTP status code. Knock does not follow redirects, so these responses are always treated as retryable failures.
• Connection errors and timeouts. This includes any request that does not receive a response within 50 seconds.

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

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

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.

1. Split the x-webhook-signature on the comma (",") and extract the values of timestamp and signature.

2. Construct the value of the signature by concatenating:

   • The timestamp (as a string)
   • The character .
   • The stringified JSON payload

3. Generate the signature with an HMAC and SHA256 algorithm using the signing key from your webhook's channel configuration.

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