Skip to main content
Cimento sends each event to your endpoint as one POST request with a JSON body.

The request

The envelope

Every event has the same four fields:
Example event
The example is spread over several lines to make it readable. A real body is compact, on one line.

Reading the body

  • Parse times, don’t compare them as text. occurredAt and the times inside data are RFC 3339 in UTC, but the number of decimal places varies: 2026-11-12T16:42:07Z and 2026-11-12T16:42:07.318Z are both possible.
  • Don’t rely on the order of fields inside data.
  • Ignore what you don’t recognize. Write your receiver to skip fields it doesn’t know, and to answer 2xx for a type it doesn’t handle. An endpoint set to All events, including any added later receives new kinds of event as Cimento adds them.
  • A person is always user. Wherever an event is about an employee, user has their Cimento id and their email. email can be null when the person is no longer in your directory.
  • actorId is the admin who made a change. It is null when Cimento made the change itself.

Reading events with an SDK

The Cimento SDKs for Go and TypeScript return each event with data typed for its type, so you don’t parse the body yourself. They follow the rules above for you. An event is still verified and handed to you when the SDK can’t type it: its type was added to Cimento after your version of the SDK, or its data doesn’t fit the type. You get that event untyped: A field the SDK doesn’t know is ignored in Go and left in event.data in TypeScript. Fields with a set of values today, such as completedBy, are plain strings in both, because more values can be added.

Respond quickly

Answer with any 2xx status within 10 seconds. Anything else is a failed attempt, which Cimento retries:
  • a status outside 200 to 299, including a 3xx redirect;
  • no answer within 10 seconds, counting the time to connect;
  • a connection or certificate error.
To stay inside 10 seconds, verify the signature, store the event, answer, and do the real work afterwards. Cimento ignores the response body, apart from keeping the start of it in the delivery log to help you debug.

Duplicates

Cimento delivers each event at least once, so your endpoint can receive the same event more than once: for example when it answered too late, and Cimento sent the event again. Use webhook-id (the same value as the body’s id) to recognize an event you have already handled, and answer 2xx without handling it twice.

Order

Events are not delivered in the order they happened. Requests can arrive in parallel, and a retried event arrives after newer ones. Use occurredAt to put events in order, and don’t assume the first event you receive about something is the first that happened.

How soon events arrive

These are typical times, not guarantees. Events take longer when Cimento is working through a backlog, or when your endpoint has been failing and deliveries to it are paused.

Test events

Send test event sends an event of type webhook.test to one endpoint, whatever events it subscribes to:
webhook.test
A test event is signed, retried and listed in the delivery log like any other. A failed test counts toward the endpoint’s failures too.