Skip to main content

Webhook Troubleshooting

Diagnose and resolve common webhook delivery and processing issues.

Checking Webhook Status​

Delivery History​

View recent deliveries:

  1. Go to Account → Webhooks
  2. Click on your webhook
  3. View Delivery History

Each entry shows:

  • Event type
  • Timestamp
  • Status (success/failed)
  • Response code
  • Response time

Failed Deliveries​

Click on a failed delivery to see:

  • Request payload
  • Response body
  • Error message
  • Retry count

Common Issues​

Webhook Not Receiving Events​

Symptoms:

  • No requests hitting your server
  • Empty delivery history

Causes & Solutions:

  1. Webhook disabled

    • Check webhook status in dashboard
    • Toggle enabled if off

  2. Wrong events selected

    • Verify subscribed to correct events
    • Edit webhook to add events

  3. URL unreachable

    • Test URL is accessible
    • Check firewall rules
    • Verify HTTPS certificate

  4. Rate limited

    • Check if exceeding limits
    • Events may be queued

Signature Verification Failing​

Symptoms:

  • Receiving requests but verification fails
  • 401 errors in your logs

Causes & Solutions:

  1. Wrong secret

    • Verify secret matches exactly
    • Check for extra whitespace
    • Regenerate if unsure

  2. Body parsing issues

    • Verify using raw body for signature
    • Check JSON isn't being modified

  3. Encoding issues

    • Ensure UTF-8 encoding
    • Check for character encoding problems

Debug snippet:

app.post('/webhook', (req, res) => {
  console.log('Raw body:', req.rawBody);
  console.log('Signature:', req.headers['x-tagd-signature']);
  console.log('Expected:', computeSignature(req.rawBody));

  // Compare and debug
});

Events Arriving Late​

Symptoms:

  • Events arrive minutes/hours after occurrence
  • Inconsistent timing

Causes & Solutions:

  1. Your endpoint is slow

    • Improve response time
    • Process asynchronously
    • Respond immediately, process later

  2. Previous failures causing retries

    • Check delivery history for failures
    • Fix underlying issues

  3. High volume causing queuing

    • Events processed in order
    • Burst traffic may queue

Duplicate Events​

Symptoms:

  • Same event received multiple times
  • Duplicate processing in your system

Causes & Solutions:

  1. At-least-once delivery (by design)

    • Implement idempotency
    • Use event ID for deduplication

  2. Slow response triggering retry

    • Respond within 30 seconds
    • Optimize processing time

Deduplication example:

const processed = new Set();

function handleEvent(event) {
  if (processed.has(event.id)) {
    console.log('Duplicate, skipping:', event.id);
    return;
  }

  processed.add(event.id);
  // Process event
}

Wrong Response Codes​

Symptoms:

  • tagd-ai shows failures
  • Your server returns errors

Causes & Solutions:

  1. Returning non-2xx codes

    • Return 200-299 for success
    • Any other code = failure = retry

  2. Exceptions in handler

    • Add error handling
    • Return 200 even if processing fails async

Correct pattern:

app.post('/webhook', async (req, res) => {
  // Respond immediately
  res.sendStatus(200);

  try {
    // Process async
    await processEvent(req.body);
  } catch (error) {
    // Log but don't fail the webhook
    console.error('Processing error:', error);
  }
});

Timeout Errors​

Symptoms:

  • Requests timing out
  • Retries being triggered

Causes & Solutions:

  1. Processing takes too long

    • tagd-ai waits 30 seconds max
    • Respond quickly, process async

  2. External API calls in handler

    • Don't make slow API calls synchronously
    • Queue for background processing

  3. Database operations

    • Optimize queries
    • Use connection pooling
    • Consider async processing

Events Missing Data​

Symptoms:

  • Expected fields not present
  • Null or undefined values

Causes & Solutions:

  1. Event type different than expected

    • Check event field first
    • Different events have different data

  2. Optional fields

    • Some fields may not always be present
    • Handle gracefully

  3. Schema changes

    • Check changelog for updates
    • Handle unknown fields gracefully

Debugging Tools​

Test Webhook Feature​

Send test events from dashboard:

  1. Go to Webhooks → select webhook
  2. Click Send Test
  3. Choose event type
  4. View result

Request Inspection​

Use services to inspect requests:

Local Development​

Tunnel to localhost:

# ngrok
ngrok http 3000

# Use the https URL as your webhook endpoint

Logging​

Add comprehensive logging:

app.post('/webhook', (req, res) => {
  console.log('=== Webhook Received ===');
  console.log('Headers:', JSON.stringify(req.headers, null, 2));
  console.log('Body:', JSON.stringify(req.body, null, 2));
  console.log('========================');

  // Process...
});

Retry Behavior​

Retry Schedule​

When delivery fails:

  • Retry 1: 1 minute
  • Retry 2: 5 minutes
  • Retry 3: 30 minutes
  • Retry 4: 2 hours
  • Retry 5: 24 hours

Webhook Disabled​

After 5 consecutive failures:

  • Webhook is automatically disabled
  • Email notification sent
  • Re-enable manually after fixing

Manual Retry​

Retry specific deliveries:

  1. Go to delivery history
  2. Find failed delivery
  3. Click Retry
  4. Monitor result

Getting Help​

Information to Provide​

When contacting support:

  1. Webhook ID
  2. Delivery IDs (from history)
  3. Event types affected
  4. Error messages
  5. Your server logs
  6. Steps to reproduce

Support Channels​

Prevention Best Practices​

Design for Reliability​

  1. Idempotent handlers - Process same event multiple times safely
  2. Quick responses - Respond fast, process async
  3. Error handling - Catch all exceptions
  4. Monitoring - Alert on failures

Testing​

  1. Use test events before production
  2. Test all subscribed event types
  3. Test error scenarios
  4. Test high-volume scenarios

Monitoring​

  1. Log all webhook requests
  2. Track success/failure rates
  3. Alert on high failure rates
  4. Monitor processing time

Next Steps​