Skip to main content

Build webhook consumers to subscribe to events

Configure new webhook consumers in Codat and manage existing configuration to receive webhook events

Overview

A webhook consumer is your implementation of a POST endpoint that you built to receive Codat's webhooks. In general, you need one consumer per event type.

This consumer must return a 2XX (status code 200-299) response within 15 seconds of receiving the POST request. We recommend passing the event to an internal message queue so that you can process it in time.

Configure webhook consumer

Once you have built your webhook consumer, configure Codat to send events to this consumer. Navigate to Settings > Webhooks > Events > Configure consumer and click Add endpoint to create a new consumer.

Building architectures with many consumers

If you are planning to create an application with more than 50 consumers, reach out to your Codat contact so that we can optimize the solution for your use case.

Add the endpoint URL that you want to receive the messages, an optional description, and choose the events that this endpoint should listen to. You must specify a least one event type per endpoint.

Browse our event catalog in the Portal or in our documentation to choose the event types that suit your use case.

Configure a consumer via the API

You can create a webhook consumer programmatically using our Create webhook endpoint.

IP allowlist

If your consumer endpoint is behind a firewall or NAT, you'll need to allow-list IP addresses 4.159.114.108 and 20.117.190.191.

Custom headers

Once you created your webhook consumer, you can use its advanced functionality to add a custom header to the endpoint. This can be useful in the following scenarios:

  • If you are securing your webhook endpoints with an authorization header, you can add it as a custom Authorization header.

  • If you are using multiple Codat instances and need to differentiate between them, add a X-Codat-ClientId header with the required client ID. You can find and copy your client ID in the Portal by clicking on your instance dropdown.

    A fragment of the UI that displays the dropdown with client instances and current client details

It's not possible to add a custom header via our API. Instead, navigate to Monitor > Webhooks > Events and click on the relevant endpoint to see its detailed view. Then, select the Advanced tab and add your headers to the custom header section.

A fragment of the webhook UI that displays the detailed endpoint view with two custom headers added to it

Filter webhooks by company tags

You can configure a webhook consumer to filter companies based on tags you can add to a company profile. For example, if you want to receive webhooks only for companies tagged with a specific region or service, you can configure the consumer to match those tags.

To set this up in the Codat Portal, navigate to Monitor > Webhooks > Events and select the relevant endpoint to view its details. Then, enter the tags you want to filter by in the Company tags field. Each webhook consumer can support up to 10 company tags.

Tags must be formatted as key-value pairs separated by a colon. For example, to route webhooks for companies tagged with a region value of us, set the Company tags field to region:us. Any company tagged with a region value of uk will be ignored.

A message will be delivered every time any of the company’s tags match the tags specified in the webhook consumer. For example, a consumer configured with region:us and service:t2k will still receive messages from a company tagged with region:us and service:minerva because one company tag matches.

A fragment of the webhook UI that allows you to add company tags to a consumer

View webhook consumers

In the Codat Portal, navigate to Monitor > Webhooks > Events to see the list of all consumer endpoints you have configured.

Alternatively, you can use the List webhooks endpoint to return a list of all consumers that currently exist for your client.

Delete webhook consumers

In the Codat Portal, navigate to Monitor > Webhooks > Events to see the list of your webhook consumers. Click on the one you want to delete, then click on the triple-dot options menu and choose Delete.

Alternatively, you can use the Delete webhook endpoint to delete an existing webhook consumer. You need to provide its valid webhookId as a parameter.

Test a webhook consumer

When adding a webhook consumer endpoint, you may want to test it with an example event to confirm its configuration. Once you have created the endpoint, click on it to see the detailed view, and navigate to the Testing tab.

Next, choose the example event you want to send and click Send example. Once it's sent, you can click into the message to view its payload, attempts, and status.

Troubleshoot failed messages

There are many reasons a message to your endpoint could fail. Have a look at our troubleshooting guide to resolve the most common issues that occur.

Verify webhook signature

A webhook signature is your way to verify that the messages are sent by Codat and helps you avoid impersonation or replay attacks. We sign every webhook and its metadata with a unique security key for each endpoint and include timestamps for when the message attempt occurred.

You can use this signature to verify that the message truly came from Codat before processing it. To do the verification, we suggest using a library called Svix.

Install library

NPM
npm install svix
Yarn
yarn add svix

Verify webhook

To verify incoming webhooks, retrieve the secret key for your endpoint first.

In the Codat Portal, navigate to Monitor > Webhooks > Events, click the endpoint you want to verify, and copy the Signing secret from the endpoint's detailed view.

A fragment of the UI that highlights where to copy the signing secret

Next, you need to pass the secret key, request body, and headers to the verification library as demonstrated below.

Use the raw request body

You need to use the raw request body when verifying webhooks because the cryptographic signature is very sensitive to changes.

Watch out for frameworks that parse the request as JSON and then stringify it, because this will also break the signature verification.

import { Webhook } from "svix";

const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

// These were all sent from the server
const headers = {
"webhook-id": "msg_p5jXN8AQM9LWM0D4loKWxJek",
"webhook-timestamp": "1614265330",
"webhook-signature": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=",
};
const payload = '{"test": 2432232314}';

const wh = new Webhook(secret);
// Throws on error, returns the verified content on success
const payload = wh.verify(payload, headers);


Was this page useful?
👏
👍
🤔
👎
😭