> ## 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.

# Webhooks

> Send Cimento's phishing, training and Agent Hub events to your own systems as they happen: who can set it up, what your endpoint needs, and how to add one.

A webhook endpoint is a URL on your side that Cimento sends an HTTPS request to each time something happens, such as an employee clicking a simulation or finishing a training. Use webhooks to feed a SIEM, open tickets, or keep another system in step with Cimento without polling.

Each request carries one event as JSON and is signed, so you can check it came from Cimento.

## In this guide

> [card] [Receiving events](https://docs.cimento.ai/webhooks/receiving-events.md)
>
> What a request looks like, how to answer it, and what to expect about duplicates, order and timing.

> [card] [Verifying signatures](https://docs.cimento.ai/webhooks/verifying-signatures.md)
>
> Check each request with your signing secret, using a Cimento SDK or code you can copy.

> [card] [Delivery and retries](https://docs.cimento.ai/webhooks/delivery-and-retries.md)
>
> What happens when your endpoint fails, and how to send events again.

> [card] [Event reference](https://docs.cimento.ai/webhooks/phishing-events.md)
>
> Every event, with its fields and an example: [Phishing](https://docs.cimento.ai/webhooks/phishing-events.md), [Training](https://docs.cimento.ai/webhooks/training-events.md) and [Agent Hub](https://docs.cimento.ai/webhooks/agent-hub-events.md).

## SDKs

Cimento publishes SDKs for Go and TypeScript. Each verifies a request and returns the event with its `data` typed.

```bash Go theme={null}
go get github.com/cimento-ai/cimento-sdk/go/webhooks
```

```bash TypeScript theme={null}
npm install @cimento/webhooks
```

[Verifying signatures](https://docs.cimento.ai/webhooks/verifying-signatures.md#verify-with-a-cimento-sdk) shows a receiver in each. For other languages, the same page covers the Standard Webhooks libraries and the check itself.

## Before you start

* **Webhooks turned on.** Webhooks are turned on for each organization. If you don't see **Webhooks** under **Admin → Integrations**, ask your Cimento contact to turn it on.
* **A Cimento admin.** People in the **Admin** and **Integrations Admin** permission groups can manage webhooks. If you were just added to one of those groups, sign out and back in.
* **An endpoint that meets the requirements below.**

## Endpoint requirements

| Requirement | Detail |
| - | - |
| HTTPS | The URL must start with `https://`, with a certificate a browser would trust. |
| Port 443 | No other port is supported. |
| A public address | The host must be a public name or address. Cimento refuses private, loopback and internal addresses, including when a public name resolves to one. |
| No credentials in the URL | A URL with a username or password, such as `https://user:pass@example.com`, is refused. So is one with a `#` fragment. |
| Answers within 10 seconds | Respond with any `2xx` status within 10 seconds. See [Receiving events](https://docs.cimento.ai/webhooks/receiving-events.md#respond-quickly). |
| No redirects | Cimento does not follow redirects. A `3xx` response counts as a failure. |

The URL can be up to 2,048 characters. A query string is allowed, but don't put a secret in it: use the [signature](https://docs.cimento.ai/webhooks/verifying-signatures.md) to check that a request is genuine. If your receiver expects a token instead, send it in a [custom header](#custom-headers).

## Add an endpoint

**1. Open Webhooks**

Go to **Admin → Integrations**. Under **Data & tooling**, open **Webhooks**, then click **Add endpoint**.

**2. Enter the URL**

Enter your **Endpoint URL**. The **Description** is optional and only shown to your admins, so use it to say what the endpoint is for.

**3. Choose the events**

Under **Events to send**, choose one:

* **All events, including any added later.** Your endpoint receives every event, and new kinds of event as Cimento adds them.
* **Choose events.** Tick the events you want. They are grouped under **Phishing**, **Training** and **Agent Hub**, and each group's checkbox selects all of it.

![The Add endpoint dialog with an endpoint URL and description entered, Choose events selected, and the Phishing events ticked](https://mintcdn.com/cimento/n6nGSMtgFNGbPpHJ/images/webhooks/add-endpoint.png?fit=max\&auto=format\&n=n6nGSMtgFNGbPpHJ\&q=85\&s=8fdfc9e0a19fe5125cdfec9a0b8bd4cd)

Webhooks › Add endpoint › Choose events

**4. Add custom headers, if your receiver needs them**

Under **Custom headers**, click **Add header** and enter a name and value for each header your receiver expects. See [Custom headers](#custom-headers).

**5. Copy the signing secret**

Click **Add endpoint**. Cimento shows **Your signing secret**. Click **Copy** and store it somewhere safe, such as your secrets manager, then click **Done**.

![The Your signing secret dialog, with the secret hidden, Reveal and Copy buttons, and a Done button](https://mintcdn.com/cimento/n6nGSMtgFNGbPpHJ/images/webhooks/signing-secret.png?fit=max\&auto=format\&n=n6nGSMtgFNGbPpHJ\&q=85\&s=efcad34e6656dcdd872e22ce7152aff6)

The signing secret is shown once

> [!WARNING]
>
> The secret is shown once. If you lose it, [rotate the secret](https://docs.cimento.ai/webhooks/verifying-signatures.md#rotate-the-secret) to get a new one.

**6. Send a test event**

On the endpoint's row, open the **⋯** menu and choose **Send test event**. Cimento sends a [`webhook.test`](https://docs.cimento.ai/webhooks/receiving-events#test-events) event, signed like any other. Click **View delivery** on the confirmation to see how your endpoint answered.

Your endpoint starts receiving events as they happen. Events from before you added it are not sent.

![The Webhooks page listing one endpoint with its URL, description, All events and an Active status, and its actions menu open](https://mintcdn.com/cimento/n6nGSMtgFNGbPpHJ/images/webhooks/endpoints.png?fit=max\&auto=format\&n=n6nGSMtgFNGbPpHJ\&q=85\&s=14c01d5a3b766943022cedd7f98b5682)

Each endpoint with its events and status

## Custom headers

Some receivers can't check a signature and expect a token in a request header instead, such as `x-api-client-token` or `X-RunReveal-Token`. Add the header to the endpoint, and Cimento sends it with every delivery, including test events and retries. The request is still signed, so a receiver that can check the signature should.

| Rule | Details |
| - | - |
| Up to 10 headers | Each endpoint can have 10 custom headers. |
| Names | Up to 64 characters: letters, digits, hyphens and the other characters HTTP allows in a header name. Each name can be used once. Case doesn't matter. |
| Values | Up to 2,048 printable ASCII characters. |
| Reserved names | You can't set `Content-Type`, `Content-Length`, `Content-Encoding`, `Host`, `User-Agent`, `Connection`, `Transfer-Encoding`, `TE`, `Trailer`, `Upgrade`, `Keep-Alive` or `Expect`, or any name that starts with `webhook-` or `proxy-`. |

Cimento encrypts header values and never shows them again. When you edit an endpoint, each saved header shows **Value saved**:

* To change a value, click **Replace** and enter the new one.
* To stop sending a header, click the **✕** beside it.

> [!NOTE]
>
> If you change the endpoint URL, you must enter every header value again. This stops a saved token from being sent to a receiver it wasn't meant for.

## Manage an endpoint

Each endpoint's **⋯** menu has:

| Action | What it does |
| - | - |
| **View deliveries** | Opens the endpoint's [delivery log](https://docs.cimento.ai/webhooks/delivery-and-retries.md#the-delivery-log). Clicking the endpoint's URL does the same. |
| **Edit** | Changes the URL, description, events or [custom headers](#custom-headers). The signing secret stays the same. |
| **Send test event** | Sends a `webhook.test` event. Available while the endpoint is active. |
| **Rotate secret** | Creates a new signing secret. The old one keeps working for 24 hours. See [Rotate the secret](https://docs.cimento.ai/webhooks/verifying-signatures.md#rotate-the-secret). |
| **Disable** / **Enable** | Stops or restarts events to the endpoint. |
| **Delete** | Removes the endpoint for good. |

## Things to know

* **Up to 10 endpoints.** Disabled endpoints count toward the limit. Delete one to add another.
* **Each endpoint gets its own copy.** If two endpoints subscribe to the same event, both receive it, with the same event `id`.
* **Events aren't saved up for you.** Cimento records an event only if an active endpoint subscribes to it at that moment. Events that happen while an endpoint is disabled, or before you subscribe it to that kind of event, are not sent later.
* **Disabling or deleting cancels what's waiting.** Deliveries that haven't been sent yet are cancelled. After you enable an endpoint again, you can [retry them](https://docs.cimento.ai/webhooks/delivery-and-retries.md#send-deliveries-again).
* **No fixed source address.** Don't rely on the IP address requests come from to decide whether they are genuine. Verify the signature instead.


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