Telivy Webhook
This guide will help you integrate with Telivy’s webhook system to receive real-time updates when certain events occur in your agency’s account
Table of Contents
- Introduction
- Webhook Events
- Setting Up Webhooks
- Processing Webhooks
- Authentication
- Custom Authentication Headers
- Payload Encryption
- Handling Webhook Data
- Troubleshooting
Introduction
Introduction
Webhooks provide a way for your systems to receive real-time notifications when specific events occur in Telivy. When an event happens, we’ll send an HTTP POST request to the URL you specified when setting up the webhook.
Webhook Events
Webhook Events
Currently, Telivy supports the following webhook events:
- ASSESSMENT_STATUS_CHANGED: Triggered when an assessment’s status changes
- ALERT_RAISED: Triggered when an alert is raised for your agency
Setting Up Webhooks
Setting Up Webhooks
Webhooks are set up through your Telivy dashboard. For each webhook, you’ll need to specify:
- A destination URL that will receive the webhook requests
- The events you want to subscribe to
- Whether you want the payload to be encrypted
- Any additional HTTP headers you want us to include in the request
When you create a webhook subscription, we’ll generate a secret key that you’ll use to verify the authenticity of webhook requests and decrypt encrypted payloads.
Processing Webhooks
Processing Webhooks
Best Practices
When processing webhooks, we recommend the following approach:
- Receive the webhook data
- Verify the signature to ensure the request is from Telivy
- Return a 2xx response immediately (preferably a 200 OK)
- Process the webhook data asynchronously after returning the response
This approach ensures that your webhook endpoint responds quickly, preventing timeouts and unnecessary retries from our system. Our webhook requests will time out after 10 seconds.
HTTP Response Codes
- 2xx: Success - We’ll consider the webhook delivered
- Other status codes: Failure - We will retry sending the webhook, first time right after, second time with a delay
Authentication
Authentication
Every webhook request includes a signature in the X-Telivy-Signature
header. You should verify this signature to ensure the request is legitimate and comes from Telivy.
The signature is an HMAC-SHA256 hash of the entire request body, using your webhook secret as the key.
Verifying the Signature
Here are examples of how to verify the signature in various programming languages:
JavaScript/Node.js
C#
Java
Python
PHP
Custom Authentication Headers
Custom Authentication Headers
In addition to verifying that webhooks are coming from Telivy using the signature, you may need to secure your webhook endpoint from unauthorized access. Telivy allows you to specify custom headers that will be included in webhook requests, which you can use for authentication in your system.
Setting Up Custom Authentication Headers When creating or updating a webhook subscription in your Telivy dashboard, you can specify custom HTTP headers to be included in all webhook requests to your endpoint. Common authentication headers include:
Authorization
: For JWT bearer tokens, OAuth tokens, or Basic AuthX-API-Key
: For API key authenticationX-Client-ID
andX-Client-Secret
: For client credential authentication
Examples of Custom Header Authentication
API Key Authentication Example custom headers configuration in Telivy:
Your webhook handler can then verify this header:
Bearer Token Authentication Example custom headers configuration in Telivy:
Your webhook handler can then verify this token:
Basic Auth Example custom headers configuration in Telivy:
Your webhook handler would then decode and verify:
Security Considerations When using custom authentication headers:
- Use HTTPS: Always ensure your webhook endpoint uses HTTPS to prevent header interception.
- Multiple Layers: Consider implementing both custom header authentication and Telivy signature verification for enhanced security.
- Rotation: Periodically rotate API keys, tokens, or passwords used in custom headers.
- Minimal Privileges: The authentication credentials used in webhook headers should have the minimal privileges needed.
Payload Encryption
Payload Encryption
For added security, you can choose to encrypt the payload data when setting up your webhook. When encryption is enabled:
- Only the data field of the payload is encrypted (the metadata field remains unencrypted)
- The encryption uses AES-256-CBC
- The initialization vector (IV) is included in the payload in the iv field
- The metadata.encrypted flag is set to true
Decrypting the Payload
When you receive an encrypted webhook, you’ll need to decrypt the data before processing it. Here are examples of how to decrypt the payload in various programming languages:
C#
Java
Python
PHP
Handling Webhook Data
Handling Webhook Data
Each webhook payload follows this structure:
For encrypted payloads:
Using Metadata
The metadata field contains important information about the webhook:
- eventType: Identifies what triggered the webhook (e.g., ASSESSMENT_STATUS_CHANGED)
- timestamp: When the event occurred (ISO 8601 format)
- webhookId: Your webhook subscription ID
- attemptNumber: Number of attempts made to deliver this webhook
- encrypted: Whether the payload data is encrypted
You can use this metadata to:
- Route the webhook to different handlers based on the event type
- Track delivery attempts for monitoring and debugging
- Detect encryption to know whether decryption is needed
- Correlate events using the timestamp for reporting
HTTP Headers
Each webhook request includes these headers:
- Content-Type: Always application/json
- User-Agent: Telivy-Webhook-Sender/1.0
- X-Telivy-Signature: HMAC-SHA256 signature for verification
- X-Telivy-Event: The event type that triggered the webhook
- X-Webhook-ID: Your webhook subscription ID
- Any custom headers you specified when creating the webhook
Troubleshooting
Troubleshooting
Common Issues
- Invalid Signature: Ensure you’re using the correct webhook secret. The entire request body must be used when verifying the signature.
- Decryption Failures: Make sure you’re using the correct algorithm (AES-256-CBC) and properly decoding the base64-encoded data and IV.
- Timeout Errors: If your endpoint doesn’t respond within 10 seconds, we may retry the webhook. Process data asynchronously after returning a response.
- Missing Events: Verify that your webhook subscription is active and subscribed to the events you’re expecting.
- Authentication Issues: Double-check that any custom authentication headers are correctly configured in your webhook subscription and properly validated by your endpoint.
Debugging Tips
- Log the raw webhook payload for investigation
- Check signature verification logic using the examples provided
- Verify that your endpoint is accessible from external sources
- Set up monitoring to track webhook receipts and processing success rates
- When testing, temporarily log all headers received to ensure custom authentication headers are being properly sent
For additional help, please contact Telivy support (support@telivy.com).