Webhooks

Receive real-time change notifications to your own applications.

Overview

Webhooks allow PageDrifter to send real-time notifications to your applications when changes are detected. Instead of polling our API, your server receives a POST request with change data.

Setting Up Webhooks

1. Go to Settings → Notifications in your dashboard
2. Click "Add Webhook"
3. Enter your webhook URL (must be HTTPS)
4. Optionally add a signing secret for verification
5. Select which events should trigger the webhook
6. Save and test the webhook

Webhook Payload

When a change is detected, PageDrifter sends a POST request to your webhook URL with the following JSON payload:

{
  "event": "change.detected",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "monitor": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Competitor Pricing",
      "url": "https://example.com/pricing"
    },
    "check": {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "status": "changed",
      "change_percentage": 12.5,
      "response_time_ms": 450,
      "checked_at": "2024-01-15T10:30:00.000Z"
    },
    "diff": {
      "additions": 5,
      "deletions": 2
    }
  }
}

Event Types

Signature Verification

To verify that webhook requests come from PageDrifter, we include a signature in the X-PageDrifter-Signature header.

// Node.js example
const crypto = require('crypto');

function verifySignature(body, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-pagedrifter-signature'];
  const isValid = verifySignature(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process the webhook...
});

Retry Policy

If your webhook endpoint returns an error (4xx or 5xx status), we'll retry the request:

• 3 retry attempts with exponential backoff
• Retries at approximately 1, 2, and 4 seconds
• After all retries fail, the webhook is marked as failed

Best Practices

Popular Integrations

Use webhooks to connect PageDrifter with your favorite tools:

Testing Webhooks

You can test your webhook configuration from the dashboard:

1. Go to Settings → Notifications
2. Find your webhook configuration
3. Click "Send Test" to send a test payload
4. Verify your endpoint receives and processes the test event