> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.komo.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Events

> Send events into Komo from external systems, and optionally require an authentication key on the Event URL.

Custom Events let you define an event in your workspace and accept `POST` requests from an external system on a public **Event URL**.

If you do not create any authentication keys, that URL stays open: anyone who has the URL can send a request. Once you create at least one key, published requests must include a valid key.

## Create a Custom Event

Open **CRM**, then go to **Contacts** → **Custom Events**, and create a new event. In the **Create Custom Event Schema** modal, enter a **Name** and optional **Description**, then click **Create**.

![Create Custom Event Schema modal with Name and Description fields](https://mintcdn.com/komotechnologies/U3G19g6j2otDbCpN/images/custom-events-create-schema-modal.webp?fit=max\&auto=format\&n=U3G19g6j2otDbCpN\&q=85\&s=c81338dff61e29d4c128d2d971a03b14)

## Find the Event URL

1. Open **CRM**, then go to **Contacts** → **Custom Events**.
2. Open the Custom Event you want to receive requests for.
3. On the **Event URL** card, copy the URL. The card explains: **Send a POST request with a JSON body to this URL.**

![Custom Event detail page showing the Event URL, an example curl request, Authentication Keys collapsed, and the Fields table](https://mintcdn.com/komotechnologies/U3G19g6j2otDbCpN/images/custom-events-event-detail.webp?fit=max\&auto=format\&n=U3G19g6j2otDbCpN\&q=85\&s=130364693076dab1638c0985ec56e9df)

The URL looks like:

```
https://events.{dc}.komo.cloud/catch/{schema-id}
```

`{dc}` is your workspace data centre (for example `au1` or `us1`). `{schema-id}` is the ID of this Custom Event.

Only a **Published** Custom Event accepts requests on this URL. Draft or Archived events are not available, even if you send a valid key.

## Fields

On the same page, the **Fields** table lists the properties this event accepts. Click **+** to add a field. In the **Create Schema Field** modal, enter a **Name**, optional **Description**, **Type**, whether it is **Required**, and optional **Min Length**, **Max Length**, and **Regex Validation**.

Types are String, Integer, Decimal, Boolean, Date, Time, DateTime, Object, and Array.

![Create Schema Field modal with Name, Description, Type, Required, Min Length, Max Length, and Regex Validation](https://mintcdn.com/komotechnologies/U3G19g6j2otDbCpN/images/custom-events-create-schema-field-modal.webp?fit=max\&auto=format\&n=U3G19g6j2otDbCpN\&q=85\&s=f371217e9584d3190a9f0619f35de751)

## Send an event

Send a `POST` request with a JSON object body to the Event URL, with the header `Content-Type: application/json`.

The body must include `entityId`: the Contact's Komo ID (a UUID), not an email or an external ID. Remaining keys must match the field names and types on the schema. Extra keys are ignored when the event is stored. Integer and Decimal values must be JSON numbers, not strings. For Date, Time, and DateTime fields, prefer ISO 8601 values such as `2026-11-13`, `14:30:00`, or `2026-11-13T14:30:00Z`.

A successful request returns **202 Accepted** with a `trackingId`. That means the event was queued. It can still be discarded during processing if the Contact is missing or belongs to another workspace, or if a Date, Time, or DateTime value cannot be parsed.

Error responses are plain text:

* `400` — invalid schema ID, missing or invalid `entityId`, or invalid JSON
* `401` — the Event URL has authentication keys and the Bearer token is missing or invalid
* `404` — the Custom Event is not found or is not **Published**
* `413` — the body is larger than 512 KiB
* `422` — the body failed field validation, including a missing required field
* `429` — rate limit exceeded (`Retry-After: 60`)
* `500` — schema configuration is invalid, or config lookup failed. Retry later, or check field patterns.

Workflows can record a Custom Event for a Contact with the **Add custom event** step. Incoming events do not start a workflow.

## Analytics

The **Analytics** chart on the Custom Event page shows how many events were received over time.

![Analytics chart of Custom Events received over time](https://mintcdn.com/komotechnologies/U3G19g6j2otDbCpN/images/custom-events-analytics-chart.webp?fit=max\&auto=format\&n=U3G19g6j2otDbCpN\&q=85\&s=efc5b7b92e8e3145e07d765f8213c41f)

## Authentication Keys

On the same **Event URL** card, under the **Example request**, expand **Authentication Keys**. The description is **Optionally secure your event requests.**

The accordion starts collapsed. The status on the right is **No keys configured**, or **1 key configured** / **N keys configured** once keys exist.

![Authentication Keys expanded, showing the Bearer token Authorization header, Create key, and the Keys table](https://mintcdn.com/komotechnologies/U3G19g6j2otDbCpN/images/custom-events-authentication-keys.webp?fit=max\&auto=format\&n=U3G19g6j2otDbCpN\&q=85\&s=114196d36138b271c11cf198d07f52de)

### Create a key

Admins with write access can create keys on **Draft** and **Published** Custom Events. If you only have read access, or the event is **Archived**, you can still view existing keys and copy the URL and header example, but **Create key** is hidden.

1. Expand **Authentication Keys**.
2. Click **Create key**.
3. In the **Create authentication key** modal, enter a **Key name**. This is a label so you can recognise the key later, for example `Production integration`. The name is required. You can create more than one key, and names do not have to be unique.
4. Click **Create key**.

A warning then appears: **Authentication key created: \{name}**, with the message **Save this secret now. For security reasons it will not be shown again.** Copy the secret and store it securely. The modal also tells you: **The secret will only be shown once after creation. Make sure to copy or store it securely.**

The key takes effect immediately. You do not need to save or publish the Custom Event again for the key to apply.

The **Keys** table lists each key's **Name** and **Created** time. If there are no keys, it shows: **No keys created, requests will be unauthenticated.**

> [!WARNING]
>
> You cannot delete, revoke, or rename a key after you create it. As soon as a Custom Event has at least one key, every request to its published Event URL requires a valid key, and that stays in place until a later update adds a way to revoke keys.

### Send the key with each request

The info on the card says: **Use authentication keys when you want to verify requests sent to this event URL. Send the key as a Bearer token in the Authorization header of each request.**

Send this header (you can copy the same example from the card):

```
Authorization: Bearer <your-key>
```

Replace `<your-key>` with the secret you copied when you created the key. Any valid key for that Custom Event is accepted. A key created for one Custom Event cannot be used on another.

Once at least one key exists, the **Example request** on the card also includes the Authorization header:

```bash theme={null}
curl -X POST \
  https://events.au1.komo.cloud/catch/{schema-id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-key>" \
  -d '{"entityId": "00000000-0000-0000-0000-000000000001", "field": "example"}'
```

Use your own Event URL and JSON body. If the Custom Event has no keys, omit the Authorization line; requests are accepted without it, as before.

> [!NOTE]
>
> Send the key from your server or integration. If a published Event URL has keys, a missing, malformed, or invalid Authorization header is rejected with `401 Unauthorized`. Requests to a Draft or Archived Event URL return `404`, including when a key is missing or invalid.

### Cloning a Custom Event

Cloning a Custom Event does not copy its keys. The clone stays open until you create keys on the clone itself.

Authentication keys for incoming [webhooks](https://knowledge.komo.tech/integrations-automation/webhooks.md) on a workflow work in a similar way, but those keys belong to the workflow, not to a Custom Event.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.