Skip to main content
Webhooks let the platform send real-time event notifications to a system of your choice. Whenever a relevant event occurs, such as a user clicking a simulation link or reporting a simulation, we send an HTTP POST request containing structured event data to a URL you configure. This lets you integrate with your own tooling, such as a SIEM, an HR system, a ticketing tool or a custom dashboard, without polling an API.

​
Supported events

All of these are sent to your endpoint. You cannot subscribe to a subset.
Only the first occurrence of an event is sent. If a user clicks the same simulation twice, you receive one phishing.clicked event. Bot events are never sent.

​
Before you start

You need:
  • Access to the platform with an Administrator or Partner role
  • A publicly accessible HTTPS endpoint that can receive POST requests
Non-TLS endpoints are not supported. The URL must be https://.

​
Add a webhook

1

Open the webhooks settings

Go to Settings then Integrations then Webhooks.
2

Add the webhook

Click Add webhook and enter your endpoint URL. It must be a valid https:// URL that is publicly reachable.
3

Confirm

Click Add webhook to save it.
4

Copy the signing secret

A signing secret is displayed. Copy it now, then click I’ve copied the secret.
The signing secret is shown once and cannot be retrieved later. Store it securely before closing the dialog.
To test the integration, send a test mail under Emails then Tests and interact with it.

​
Event payload

Events are delivered as JSON in the body of an HTTP POST request. Example payload:

​
Verifying authenticity

Every request includes an X-Signature header. This is an HMAC-SHA256 signature computed over the raw request body using your signing secret as the key.
1

Read the raw body

Take the raw request body, before parsing the JSON.
2

Compute the signature

Compute HMAC-SHA256 over the raw body using your signing secret.
3

Compare

Compare your result to the value in the X-Signature header.
4

Accept or reject

If they match, the request is authentic and you can process it. If they do not match, reject it with a 401 response.
Always use a timing-safe comparison function. A plain string comparison leaks information through its timing and can be used to forge a signature.

​
Retries

If your endpoint does not return an HTTP 2xx response within 10 seconds, delivery is retried automatically. After 5 failed attempts the delivery is marked as Failed.

​
Removing a webhook

1

Open the webhooks settings

Go to Settings then Integrations then Webhooks.
2

Delete it

Click Delete webhook, then confirm in the dialog.
Removing a webhook stops all future deliveries. Events that occur while no webhook is active are not queued and are not delivered retroactively.

​
Troubleshooting

For anything not listed here, contact support@outkept.com with your organisation name and your endpoint URL.