---
title: "Create webhook consumer"
method: POST
path: "/webhooks"
tags: ["Webhooks"]
---

# Create webhook consumer

`POST /webhooks`

Use the *Create webhook consumer* endpoint to create a new webhook consumer that will listen to messages we send you.

[Webhook consumer](https://docs.codat.io/platform-api#/schemas/WebhookConsumer) is an HTTP endpoint that you configure to subscribe to specific events. See our documentation for more details on [Codat's webhook service](https://docs.codat.io/using-the-api/webhooks/overview).

### Tips and traps
- The number of webhook consumers you can create is limited to 50. If you have reached the maximum number of consumers, use the [*Delete webhook consumer*](https://docs.codat.io/platform-api#/operations/delete-webhook-consumer) endpoint to delete an unused consumer first.

## Request body

- WebhookConsumerPrototype — unresolved $ref

## Response `201`

OK

- WebhookConsumer — A webhook consumer is an HTTP endpoint that developers can configure to subscribe to Codat's supported event types. See our documentation for more details on [Codat's webhook service](https://docs.codat.io/using-the-api/webhooks/overview).
  - `id` string, uuid — Unique identifier for the webhook consumer.
  - `url` string, uri — The URL that will consume webhook events dispatched by Codat.
  - `disabled` boolean, nullable — Flag that enables or disables the endpoint from receiving events. Disabled when set to `true`.
  - `eventTypes` string[] — An array of event types the webhook consumer subscribes to.
  - `companyTags` string[], nullable — Company tags provide an additional way to filter messages, independent of event types. Company tags are case-sensitive, and only messages from companies with matching tags will be sent to this endpoint. Use the format `tagKey:tagValue`.

## Other responses

- `400` — The request made is not valid.
- `401` — Your API request was not properly authorized.
- `402` — An account limit has been exceeded. The type of limit is described in the error property: - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request. - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan. - Your Free account is older than 365 days and has expired. Contact support@codat.io.
- `403` — You are using an outdated API key or a key not associated with that resource.
- `429` — Too many requests were made in a given amount of time. Wait a short period and then try again.
- `500` — There is a problem with our server. Please try again later.
- `503` — The Codat API is temporarily offline for maintenance. Please try again later.

## Changes

> 52 revisions in range; 1 could not be searched.

- **2025-01-23** `e711c7acf8df` — 1 breaking, 2 warning, 1 info
  - the response property `companyTags` became nullable for the status `201`
  - removed the request property `companyId`
  - removed the optional property `companyId` from the response with the `201` status
  - the request property `companyTags` became nullable
- **2024-10-07** `fd9017a95f3d` — 1 info
  - added the new optional request property `companyTags`
- **2024-10-07** `9da67c91c872` — 3 info
  - request property `companyId` deprecated
  - added the optional property `companyTags` to the response with the `201` status
  - response property `companyId` deprecated

[Change history](https://skmtc.dev/codatio/apis/platform-api/changes/webhooks/post.md)

---

[API](https://skmtc.dev/codatio/apis/platform-api.md) · [All operations](https://skmtc.dev/codatio/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/codatio/platform-api/revisions/bff9b9776ecf/schema)