Webhook Setup

Prerequisites

Before creating a webhook, you'll need:

• ✅ An Agency plan subscription
• ✅ A public HTTPS endpoint to receive webhooks
• ✅ Ability to verify HMAC signatures (see Security Guide)

Step 1: Create Your Webhook Endpoint

First, create an endpoint in your application that can receive POST requests. This endpoint should:

• Accept HTTP POST requests
• Parse JSON request bodies
• Verify the webhook signature (critical!)
• Return a 2xx status code on success

Example endpoint (Node.js/Express):

const express = require('express');
const app = express();

app.post('/webhooks/seo-crawler', express.json(), (req, res) => {
  // 1. Verify signature (see Security Guide)
  const signature = req.headers['x-linkhealth-signature'];
  if (!verifySignature(req.body, signature)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // 2. Process the event
  const { event, data } = req.body;
  console.log(`Received event: ${event}`, data);
  
  // 3. Return success
  res.json({ received: true });
});

app.listen(3000);

Step 2: Add Webhook in Dashboard

1. Navigate to Settings

   • Go to your dashboard
   • Click Settings in the sidebar
   • Select the API tab

2. Create Webhook

   • Click Add Webhook button
   • Fill in the form:

Endpoint URL

https://your-domain.com/webhooks/seo-crawler

• Must be HTTPS in production
• Must be publicly accessible
• Cannot be a private IP or localhost

Name (Optional)

My Server Webhook

• Helps you identify the webhook
• Maximum 100 characters

Events

• Select which events to receive
• Choose one or more:
  • ✅ Crawl Started
  • ✅ Crawl Completed
  • ✅ Crawl Failed
  • ✅ Broken Links Found

1. Create and Copy Secret
   • Click Create Webhook
   • ⚠️ IMPORTANT: Copy the signing secret immediately
   • This is the only time it will be shown
   • Store it securely (environment variable, secrets manager)

# Example secret (64 characters)
a1b2c3d4e5f6789012345678901234567890123456789012345678901234

Step 3: Test Your Webhook

After creating the webhook:

1. Use the Test Feature

   • Click the Test button next to your webhook
   • A test event will be sent to your endpoint
   • Check the response status and time

2. Check Your Logs

   • Verify your endpoint received the test event
   • Ensure signature verification passed
   • Confirm the event was processed correctly

Test Event Example:

{
  "event": "test",
  "timestamp": "2024-12-09T10:30:00Z",
  "data": {
    "message": "This is a test webhook",
    "webhook_id": "wh_abc123"
  }
}

Step 4: Monitor Deliveries

After your webhook is active:

1. View Delivery History

   • Click on your webhook in the list
   • See recent deliveries with status codes
   • Check response times and errors

2. Debug Issues

   • Failed deliveries show error messages
   • Response bodies are captured (truncated to 1000 chars)
   • Timestamps help correlate with your logs

Common Setup Issues

❌ "Cannot use private or internal IP addresses"

Problem: Your URL points to localhost or a private IP

Solution:

• Use ngrok for local testing: ngrok http 3000
• Deploy to a public server for production

❌ "URL must use HTTPS in production"

Problem: You're using HTTP in production

Solution:

• Use HTTPS (Let's Encrypt is free)
• HTTP is only allowed in development

❌ "Signature verification failed"

Problem: Your endpoint isn't verifying signatures correctly

Solution:

• Check you're using the correct secret
• Follow the Security Guide examples
• Ensure you're reading the raw request body

❌ "Timeout" or "Connection refused"

Problem: Your endpoint isn't responding within 30 seconds

Solution:

• Process webhooks asynchronously
• Return 200 immediately, then process
• Check your firewall/network settings

Managing Webhooks

Update a Webhook

You can update:

• Webhook URL
• Name and description
• Event subscriptions
• Active/inactive status

Note: You cannot change the signing secret. If compromised, delete and recreate the webhook.

Delete a Webhook

1. Click the Delete button
2. Confirm deletion
3. Webhook deliveries stop immediately

Webhook Limits

• Maximum webhooks: 10 per account (Agency plan)
• Timeout: 30 seconds per request
• Retry attempts: 3 retries with exponential backoff
• Rate limiting: No explicit limit (reasonable use)

Next Steps

✅ Webhook created and tested

Now learn how to:

• Verify signatures securely (required!)
• Handle different event types
• Implement retry logic

Local Development

For testing webhooks locally:

Option 1: ngrok (Recommended)

# Start your local server
npm start  # or node server.js

# In another terminal, expose it
ngrok http 3000

# Use the ngrok URL in webhook settings
# https://abc123.ngrok-free.app/webhooks/seo-crawler

Option 2: localtunnel

npx localtunnel --port 3000
# https://random-name.loca.lt

Security Note: Never commit your webhook secret to version control. Use environment variables:

# .env
WEBHOOK_SECRET=your-secret-here

# In your code
const secret = process.env.WEBHOOK_SECRET;