Skip to main content
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

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
The URL looks like:
{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

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

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

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.
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):
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:
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.
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 on a workflow work in a similar way, but those keys belong to the workflow, not to a Custom Event.