Skip to Content
DocsTroubleshootingWebhook Debugging

Webhook Debugging

Step-by-step guide to debugging webhook issues.

Check Webhook Logs

First, review your webhook activity:

  1. Go to Settings > Webhooks > Logs
  2. Find the timestamp of your request
  3. Review the request details and response

Log Entry Fields

FieldDescription
TimestampWhen request was received
StatusSuccess, Failed, Filtered
Request BodyThe payload sent
ResponseWhat Lead Warmer returned
ErrorError details if failed

Test with cURL

Send a test request directly:

curl -X POST https://api.leadwarmer.net/webhooks/ingest/{webhook-id} \
  -H "Content-Type: application/json" \
  -H "X-Signature-Key: {your-secret}" \
  -d '{
    "lead_id": "debug-001",
    "email": "debug@example.com",
    "first_name": "Debug",
    "last_name": "Test",
    "source": "debug"
  }' \
  -v

Expected Success Response

{
  "success": true,
  "lead_id": "generated-uuid",
  "message": "Lead accepted for processing"
}

Common Error Responses

Invalid Signature (401)

{
  "success": false,
  "error": "Invalid webhook signature",
  "code": "INVALID_SIGNATURE"
}

Fix: Check your X-Signature-Key header matches your webhook secret.

Invalid Payload (400)

{
  "success": false,
  "error": "Invalid payload: missing required field 'email'",
  "code": "INVALID_PAYLOAD"
}

Fix: Include all required fields. See Payload Format.

Rate Limited (429)

{
  "success": false,
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT",
  "retry_after": 60
}

Fix: Wait retry_after seconds before retrying.

Lead Filtered (200 but not processed)

{
  "success": true,
  "lead_id": null,
  "message": "Lead filtered by ingestion rules",
  "reason": "blocked_domain"
}

Fix: Check your ingestion rules in Settings.

Verify Payload Format

Use JSON validation:

echo '{
  "email": "test@example.com",
  "first_name": "Test"
}' | jq .

Common Payload Issues

IssueExampleFix
Invalid JSON{email: "test"}Use quotes: {"email": "test"}
Wrong content typetext/plainSet Content-Type: application/json
Encoded characters%40 in emailSend raw @ symbol
Trailing comma{"a": 1,}Remove trailing comma

Network Issues

Check DNS Resolution

nslookup api.leadwarmer.net

Check Connectivity

curl -I https://api.leadwarmer.net/health

Expected: HTTP/2 200

Check SSL Certificate

openssl s_client -connect api.leadwarmer.net:443 -servername api.leadwarmer.net

Webhook Retry Logic

If your webhook fails, implement retry logic:

async function sendWebhook(payload, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(webhookUrl, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-Signature-Key': webhookSecret
        },
        body: JSON.stringify(payload)
      });
 
      if (response.ok) return response.json();
 
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || 60;
        await sleep(retryAfter * 1000);
        continue;
      }
 
      throw new Error(`HTTP ${response.status}`);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(Math.pow(2, i) * 1000); // Exponential backoff
    }
  }
}

Request Inspection Tools

Use these tools to inspect your webhooks:

Still Having Issues?

Contact support with:

  1. Webhook log entry ID
  2. Request payload (sanitized)
  3. Response received
  4. Timestamp of the issue
Common IssuesVideo Generation