POST request with a JSON body.
The request
The envelope
Every event has the same four fields:Example event
Reading the body
- Parse times, don’t compare them as text.
occurredAtand the times insidedataare RFC 3339 in UTC, but the number of decimal places varies:2026-11-12T16:42:07Zand2026-11-12T16:42:07.318Zare 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
2xxfor atypeit 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,userhas their Cimentoidand theiremail.emailcan benullwhen the person is no longer in your directory. actorIdis the admin who made a change. It isnullwhen Cimento made the change itself.
Reading events with an SDK
The Cimento SDKs for Go and TypeScript return each event withdata 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 any2xx status within 10 seconds. Anything else is a failed attempt, which Cimento retries:
- a status outside
200to299, including a3xxredirect; - no answer within 10 seconds, counting the time to connect;
- a connection or certificate error.
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. Usewebhook-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. UseoccurredAt 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 typewebhook.test to one endpoint, whatever events it subscribes to:
webhook.test