Implement Retell AI webhook signature validation and event handling. Use when setting up webhook endpoints, implementing signature verification, or handling Retell AI event notifications securely. Trigger with phrases like "retellai webhook", "retellai events", "retellai webhook signature", "handle retellai events", "retellai notifications".
Installation
Details
Usage
After installing, this skill will be available to your AI coding assistant.
Verify installation:
skills listSkill Instructions
name: retellai-webhooks-events description: | Implement Retell AI webhook signature validation and event handling. Use when setting up webhook endpoints, implementing signature verification, or handling Retell AI event notifications securely. Trigger with phrases like "retellai webhook", "retellai events", "retellai webhook signature", "handle retellai events", "retellai notifications". allowed-tools: Read, Write, Edit, Bash(curl:*) version: 1.0.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io
Retell AI Webhooks & Events
Overview
Securely handle Retell AI webhooks with signature validation and replay protection.
Prerequisites
- Retell AI webhook secret configured
- HTTPS endpoint accessible from internet
- Understanding of cryptographic signatures
- Redis or database for idempotency (optional)
Webhook Endpoint Setup
Express.js
import express from 'express';
import crypto from 'crypto';
const app = express();
// IMPORTANT: Raw body needed for signature verification
app.post('/webhooks/retellai',
express.raw({ type: 'application/json' }),
async (req, res) => {
const signature = req.headers['x-retellai-signature'] as string;
const timestamp = req.headers['x-retellai-timestamp'] as string;
if (!verifyRetell AISignature(req.body, signature, timestamp)) {
return res.status(401).json({ error: 'Invalid signature' });
}
const event = JSON.parse(req.body.toString());
await handleRetell AIEvent(event);
res.status(200).json({ received: true });
}
);
Signature Verification
function verifyRetell AISignature(
payload: Buffer,
signature: string,
timestamp: string
): boolean {
const secret = process.env.RETELLAI_WEBHOOK_SECRET!;
// Reject old timestamps (replay attack protection)
const timestampAge = Date.now() - parseInt(timestamp) * 1000;
if (timestampAge > 300000) { // 5 minutes
console.error('Webhook timestamp too old');
return false;
}
// Compute expected signature
const signedPayload = `${timestamp}.${payload.toString()}`;
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(signedPayload)
.digest('hex');
// Timing-safe comparison
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}
Event Handler Pattern
type Retell AIEventType = 'resource.created' | 'resource.updated' | 'resource.deleted';
interface Retell AIEvent {
id: string;
type: Retell AIEventType;
data: Record<string, any>;
created: string;
}
const eventHandlers: Record<Retell AIEventType, (data: any) => Promise<void>> = {
'resource.created': async (data) => { /* handle */ },
'resource.updated': async (data) => { /* handle */ },
'resource.deleted': async (data) => { /* handle */ }
};
async function handleRetell AIEvent(event: Retell AIEvent): Promise<void> {
const handler = eventHandlers[event.type];
if (!handler) {
console.log(`Unhandled event type: ${event.type}`);
return;
}
try {
await handler(event.data);
console.log(`Processed ${event.type}: ${event.id}`);
} catch (error) {
console.error(`Failed to process ${event.type}: ${event.id}`, error);
throw error; // Rethrow to trigger retry
}
}
Idempotency Handling
import { Redis } from 'ioredis';
const redis = new Redis(process.env.REDIS_URL);
async function isEventProcessed(eventId: string): Promise<boolean> {
const key = `retellai:event:${eventId}`;
const exists = await redis.exists(key);
return exists === 1;
}
async function markEventProcessed(eventId: string): Promise<void> {
const key = `retellai:event:${eventId}`;
await redis.set(key, '1', 'EX', 86400 * 7); // 7 days TTL
}
Webhook Testing
# Use Retell AI CLI to send test events
retellai webhooks trigger resource.created --url http://localhost:3000/webhooks/retellai
# Or use webhook.site for debugging
curl -X POST https://webhook.site/your-uuid \
-H "Content-Type: application/json" \
-d '{"type": "resource.created", "data": {}}'
Instructions
Step 1: Register Webhook Endpoint
Configure your webhook URL in the Retell AI dashboard.
Step 2: Implement Signature Verification
Use the signature verification code to validate incoming webhooks.
Step 3: Handle Events
Implement handlers for each event type your application needs.
Step 4: Add Idempotency
Prevent duplicate processing with event ID tracking.
Output
- Secure webhook endpoint
- Signature validation enabled
- Event handlers implemented
- Replay attack protection active
Error Handling
| Issue | Cause | Solution |
|---|---|---|
| Invalid signature | Wrong secret | Verify webhook secret |
| Timestamp rejected | Clock drift | Check server time sync |
| Duplicate events | Missing idempotency | Implement event ID tracking |
| Handler timeout | Slow processing | Use async queue |
Examples
Testing Webhooks Locally
# Use ngrok to expose local server
ngrok http 3000
# Send test webhook
curl -X POST https://your-ngrok-url/webhooks/retellai \
-H "Content-Type: application/json" \
-d '{"type": "test", "data": {}}'
Resources
Next Steps
For performance optimization, see retellai-performance-tuning.
More by jeremylongshore
View allOauth Callback Handler - Auto-activating skill for API Integration. Triggers on: oauth callback handler, oauth callback handler Part of the API Integration skill category.
Rabbitmq Queue Setup - Auto-activating skill for Backend Development. Triggers on: rabbitmq queue setup, rabbitmq queue setup Part of the Backend Development skill category.
evaluating-machine-learning-models: This skill allows Claude to evaluate machine learning models using a comprehensive suite of metrics. It should be used when the user requests model performance analysis, validation, or testing. Claude can use this skill to assess model accuracy, precision, recall, F1-score, and other relevant metrics. Trigger this skill when the user mentions "evaluate model", "model performance", "testing metrics", "validation results", or requests a comprehensive "model evaluation".
building-neural-networks: This skill allows Claude to construct and configure neural network architectures using the neural-network-builder plugin. It should be used when the user requests the creation of a new neural network, modification of an existing one, or assistance with defining the layers, parameters, and training process. The skill is triggered by requests involving terms like "build a neural network," "define network architecture," "configure layers," or specific mentions of neural network types (e.g., "CNN," "RNN," "transformer").
