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

Receiving events

What a request looks like, how to answer it, and what to expect about duplicates, order and timing.

Verifying signatures

Check each request with your signing secret, using a Cimento SDK or code you can copy.

Delivery and retries

What happens when your endpoint fails, and how to send events again.

Event reference

Every event, with its fields and an example: Phishing, Training and Agent Hub.

SDKs

Cimento publishes SDKs for Go and TypeScript. Each verifies a request and returns the event with its data typed.
Verifying signatures 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

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 to check that a request is genuine. If your receiver expects a token instead, send it in a custom header.

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

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

The signing secret is shown once

The secret is shown once. If you lose it, 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 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

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

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.
  • No fixed source address. Don’t rely on the IP address requests come from to decide whether they are genuine. Verify the signature instead.