retellai-webhooks-events

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".

⭐939stars🔀114forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill provides a comprehensive framework for implementing secure Retell AI webhook integrations. It streamlines the development process by offering ready-to-use logic for HMAC SHA256 signature validation, replay attack protection, and idempotent event handling, ensuring that your backend communicates reliably and securely with Retell AI services.

Use Cases

  • Setting up a secure Express.js or Node.js endpoint to receive real-time notifications from Retell AI voice agents.
  • Implementing cryptographic signature verification to ensure that incoming webhook requests are authentic and originate from Retell AI.
  • Developing robust event-driven workflows to update databases or trigger business logic when calls are created, updated, or completed.
  • Preventing duplicate data processing and replay attacks using timestamp validation and Redis-based idempotency tracking.
nameretellai-webhooks-events
description|
allowed-toolsRead, Write, Edit, Bash(curl:*)
version1.0.0
licenseMIT
authorJeremy 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.