Skip to main content
Telivy webhooks send an HTTP POST request to your endpoint when something happens in Telivy, such as a finished scan, a changed grade, a new alert or an agent install, so your own systems can react without polling the API. This page covers setup, signature verification, custom authentication headers, payload encryption and troubleshooting. When one of the events below happens, Telivy sends an HTTP POST request to the URL you gave when setting up the webhook.

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.
Account → Webhooks list with two webhooks showing the active switch, URL, events, encryption, created date and Edit
Create New Webhook form with the webhook URL https://hooks.example.com/telivy, event types, Encrypt Payload switch and Headers field
When you create the subscription, Telivy generates a secret key. You use it to verify that requests come from Telivy and to decrypt encrypted payloads.

Processing webhooks

  1. Receive the request.
  2. Verify the signature to confirm the request came from Telivy.
  3. Return a 2xx response straight away, preferably 200 OK.
  4. Process the data asynchronously after responding.
Webhook requests time out after 60 seconds, so responding first and processing later avoids timeouts and unnecessary retries.

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 the X-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:
  • Authorization for bearer tokens or Basic Auth
  • X-API-Key for an API key
  • X-Client-ID and X-Client-Secret for client credentials

API key

Custom headers configured in Telivy:
Your webhook handler can then verify this header:

Bearer token

Custom headers configured in Telivy:
Your webhook handler can then verify this token:

Basic Auth

Custom headers configured in Telivy:
Your webhook handler can then decode and verify the credentials:

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 the data 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

Decrypt data before processing it. The examples below show how in four languages.

C#

Java

Python

PHP

Handling webhook data

Each webhook payload follows this structure:
For encrypted payloads:

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.

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