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

# Receiving events

> What Cimento sends to your webhook endpoint, how to answer it, and what to expect about duplicates, order and timing.

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

## The request

| Header | Value |
| - | - |
| `Content-Type` | `application/json` |
| `User-Agent` | `Cimento-Webhooks/1.0` |
| `webhook-id` | The event's `id`. The same on every attempt to deliver that event. |
| `webhook-timestamp` | When this attempt was made, in seconds since the Unix epoch. It changes on every attempt. |
| `webhook-signature` | The signature to check. See [Verifying signatures](https://docs.cimento.ai/webhooks/verifying-signatures.md). |
| Your custom headers | Any [custom headers](https://docs.cimento.ai/webhooks/overview.md#custom-headers) you added to the endpoint, with the values you saved. |

## The envelope

Every event has the same four fields:

| Field | Type | Description |
| - | - | - |
| `id` | string | A UUID that identifies the event. Use it to spot duplicates. |
| `type` | string | The kind of event, such as `training.assignment.completed`. |
| `occurredAt` | string | When it happened, as an RFC 3339 time in UTC. |
| `data` | object | The details. Its fields depend on `type`: see the [event reference](https://docs.cimento.ai/webhooks/phishing-events.md). |

```json Example event theme={null}
{
  "id": "5e0c8f0e-6a39-4f3c-9d0b-2a7c1b9d4e11",
  "type": "training.assignment.completed",
  "occurredAt": "2026-11-12T16:42:07.318Z",
  "data": {
    "assignmentId": "b2d7c1a4-3f5e-4a8b-9c6d-1e2f3a4b5c6d",
    "campaignId": "8a1f2e3d-4c5b-4a69-8877-665544332211",
    "user": {
      "id": "0f9e8d7c-6b5a-4433-9221-100f0e0d0c0b",
      "email": "ada.lovelace@example.com"
    },
    "completedAt": "2026-11-12T16:42:07.318Z",
    "completedBy": "learner"
  }
}
```

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](https://docs.cimento.ai/webhooks/verifying-signatures.md#verify-with-a-cimento-sdk) 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 typed event | An event the SDK can't type |
| - | - | - |
| Go | `event.Data` points to the payload struct for the type | `event.Data` is `nil`, and `event.RawData` holds `data` as JSON |
| TypeScript | `event.known` is `true`, and `event.data` has the type's fields | `event.known` is `false`, and `event.data` is a plain object |

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](https://docs.cimento.ai/webhooks/delivery-and-retries.md):

* 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](https://docs.cimento.ai/webhooks/delivery-and-retries.md#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

| Events | Usually arrive within |
| - | - |
| Training events, and changes an admin makes | About a minute |
| Phishing simulation outcomes, such as a click or a report | About two minutes of Cimento recording them |
| `agent_hub.finding.created` | About four minutes |

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](https://docs.cimento.ai/webhooks/delivery-and-retries.md#when-an-endpoint-keeps-failing).

## Test events

**Send test event** sends an event of type `webhook.test` to one endpoint, whatever events it subscribes to:

```json webhook.test theme={null}
{
  "id": "c7a1e2b3-4d5f-4a6b-8c9d-0e1f2a3b4c5d",
  "type": "webhook.test",
  "occurredAt": "2026-11-12T16:50:00.124Z",
  "data": {
    "endpointId": "3b9d5c2e-7f1a-4e8b-a6c4-9d0e1f2a3b4c"
  }
}
```

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.


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