Webhook Issues

Webhooks Not Received

Problem: Webhook events are not being delivered Quick Checks: Verify URL, HTTPS, response time, and network accessibility.

Verify Webhook URL

Ensure webhook URL is valid and accessible:

JavaScript
Python
HTTPie

// Test webhook endpoint
const testPayload = { test: true };
const response = await fetch('https://your-server.com/webhooks/sessions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(testPayload),
  signal: AbortSignal.timeout(10000) // 10s timeout
});

if (response.status !== 200) {
  console.log(`Webhook endpoint returned ${response.status}`);
} else {
  console.log('Webhook endpoint is accessible');
}

# Test webhook endpoint
import requests

test_payload = {"test": True}
response = requests.post(
    "https://your-server.com/webhooks/sessions",
    json=test_payload,
    timeout=10
)

if response.status_code != 200:
    print(f"Webhook endpoint returned {response.status_code}")
else:
    print("Webhook endpoint is accessible")

# Test webhook endpoint
http POST https://your-server.com/webhooks/sessions \
  test:=true \
  timeout=10

Check HTTPS

Webhook URLs must use HTTPS (HTTP will be rejected):

JavaScript
Python
HTTPie

// ✅ Correct: HTTPS
const webhookUrl = "https://your-server.com/webhooks/sessions";

// ❌ Incorrect: HTTP (will be rejected)
// const webhookUrl = "http://your-server.com/webhooks/sessions";

# ✅ Correct: HTTPS
webhook_url = "https://your-server.com/webhooks/sessions"

# ❌ Incorrect: HTTP (will be rejected)
# webhook_url = "http://your-server.com/webhooks/sessions"

# ✅ Correct: HTTPS
WEBHOOK_URL="https://your-server.com/webhooks/sessions"

# ❌ Incorrect: HTTP (will be rejected)
# WEBHOOK_URL="http://your-server.com/webhooks/sessions"

Verify Response Time

Webhook endpoints must respond quickly (within 5 seconds):

JavaScript
Python
HTTPie

// Your webhook handler should respond within 5 seconds
app.post('/webhooks/sessions', async (req, res) => {
  const payload = req.body;
  
  // Process asynchronously if needed
  setImmediate(() => processWebhook(payload));
  
  // Return immediately
  res.json({ status: 'received' }); // Must return 200 quickly
});

# Your webhook handler should respond within 5 seconds
@app.post("/webhooks/sessions")
async def handle_webhook(request: Request):
    payload = await request.json()
    
    # Process asynchronously if needed
    asyncio.create_task(process_webhook(payload))
    
    # Return immediately
    return {"status": "received"}  # Must return 200 quickly

# Test response time
time http POST https://your-server.com/webhooks/sessions \
  test:=true

Check Firewall/Network

Ensure your server accepts incoming connections:

Test from External

# Test if webhook URL is accessible from outside
http POST https://your-server.com/webhooks/sessions \
  Content-Type:application/json \
  test:=true

Duplicate Webhook Events

Problem: Receiving duplicate webhook events Solution: Implement idempotency with event tracking

JavaScript
Python
HTTPie

// Track processed events
const processedEvents = new Map();

app.post('/webhooks/sessions', async (req, res) => {
  const payload = req.body;
  
  // Create unique event ID
  const eventId = `${payload.event}_${payload.session.id}_${payload.timestamp}`;
  
  // Check if already processed
  if (processedEvents.has(eventId)) {
    return res.json({ status: 'duplicate' });
  }
  
  // Process event
  await processWebhook(payload);
  
  // Mark as processed (keep for 1 hour)
  processedEvents.set(eventId, Date.now());
  
  // Cleanup old entries
  const oneHourAgo = Date.now() - 3600000;
  for (const [id, timestamp] of processedEvents.entries()) {
    if (timestamp < oneHourAgo) {
      processedEvents.delete(id);
    }
  }
  
  res.json({ status: 'received' });
});

from datetime import datetime, timedelta

# Track processed events
processed_events = {}

@app.post("/webhooks/sessions")
async def handle_webhook(request: Request):
    payload = await request.json()
    
    # Create unique event ID
    event_id = f"{payload['event']}_{payload['session']['id']}_{payload['timestamp']}"
    
    # Check if already processed
    if event_id in processed_events:
        return {"status": "duplicate"}
    
    # Process event
    process_webhook(payload)
    
    # Mark as processed (keep for 1 hour)
    processed_events[event_id] = datetime.now()
    
    # Cleanup old entries
    cutoff = datetime.now() - timedelta(hours=1)
    processed_events = {
        k: v for k, v in processed_events.items()
        if v > cutoff
    }
    
    return {"status": "received"}

# Webhook handler would be on your server
# This shows how to test idempotency

# First request
http POST https://your-server.com/webhooks/sessions \
  event=session.created \
  session:='{"id":"123"}' \
  timestamp=1234567890

# Duplicate request (should return duplicate status)
http POST https://your-server.com/webhooks/sessions \
  event=session.created \
  session:='{"id":"123"}' \
  timestamp=1234567890

Use a database or Redis for event tracking in production instead of in-memory storage for better reliability across multiple server instances.

Webhooks Guide

Complete webhook documentation

Troubleshooting Home

Back to troubleshooting overview

Getting Started

Use Cases

Best Practices

Advanced

Troubleshooting

Webhooks Not Received

Duplicate Webhook Events

Webhooks Guide

Troubleshooting Home

Getting Started

Use Cases

Best Practices

Advanced

Troubleshooting

​Webhooks Not Received

​Duplicate Webhook Events

​Related Guides

Webhooks Guide

Troubleshooting Home

Webhooks Not Received

Duplicate Webhook Events

Related Guides