Webhook events
Events go to the webhooks of the agency that owns the assessment. A master agency receives its sub-agencies’ events only on webhooks created with sub-agencies included, and every payload carries the owning
agencyId.
Setting up webhooks
Set up webhooks in the Telivy portal under Account → Webhooks. For each webhook you set the destination URL, the events to subscribe to, whether the payload is encrypted, and any extra HTTP headers Telivy should send.

Processing webhooks
Recommended handling
- Receive the request.
- Verify the signature to confirm the request came from Telivy.
- Return a 2xx response straight away, preferably
200 OK. - Process the data asynchronously after responding.
HTTP response codes
Any 2xx response counts as delivered. Any other status code, or a timeout, counts as a failure, and Telivy retries with increasing delays, up to 3 attempts in total.metadata.attemptNumber tells the attempts apart. A delivery can arrive more than once, so make your handler safe to run twice for the same event.
Authentication
Every webhook request carries a signature in theX-Telivy-Signature header. Verify it to confirm the request came from Telivy.
The signature is the hex-encoded HMAC-SHA256 of the raw request body, with your webhook secret as the key. Compute it over the body exactly as received, before any JSON parsing.
Verifying the signature
The examples below verify the signature in five languages.JavaScript/Node.js
C#
Java
Python
PHP
Custom authentication headers
If your endpoint requires its own authentication, add custom headers to the webhook subscription. Telivy sends them on every request, alongside the signature. Common choices are:Authorizationfor bearer tokens or Basic AuthX-API-Keyfor an API keyX-Client-IDandX-Client-Secretfor client credentials
API key
Custom headers configured in Telivy:Bearer token
Custom headers configured in Telivy:Basic Auth
Custom headers configured in Telivy:Security notes
Serve the endpoint over HTTPS so the headers cannot be read in transit. Check both the custom header and the Telivy signature. Rotate the keys, tokens or passwords you put in custom headers from time to time, and give those credentials only the access the webhook endpoint needs.Payload encryption
You can turn on payload encryption when setting up a webhook. With encryption on, only thedata field is encrypted, using AES-256-CBC. The metadata field stays readable, metadata.encrypted is true, and the initialization vector is sent in the iv field.
Decrypting the payload
Decryptdata before processing it. The examples below show how in four languages.
C#
Java
Python
PHP
Handling webhook data
Each webhook payload follows this structure:Metadata fields
Use
eventType to route requests to the right handler, attemptNumber to spot retries, and encrypted to decide whether to decrypt.
HTTP headers
Any custom headers you set on the webhook are sent as well.
Troubleshooting
Common problems
While debugging, log the raw body and all headers your endpoint receives, and confirm the endpoint is reachable from the internet. If you are still stuck, contact support@telivy.com.
Related guides
n8n
Route webhook events to Slack, Teams, Sheets, and more
Alerts
The alerts behind the ALERT_RAISED event
Security API
Read and manage Telivy data from your own tools