Webhooks

Webhooks allow you to receive real-time HTTP notifications when events occur in Captureze.

Setting Up Webhooks

1. Go to Settings → Webhooks
2. Click Add Webhook
3. Enter your endpoint URL (must be HTTPS)
4. Select which events to receive
5. Save the webhook

Events

Payload Format

Webhook payloads are sent as JSON in the request body:

screenshot.captured

{
  "event": "screenshot.captured",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "scheduleId": "uuid",
    "scheduleName": "Example Monitor",
    "url": "https://example.com",
    "screenshotId": "uuid",
    "screenshotUrl": "https://captureze.com/screenshots/...",
    "diffPercent": 0.5,
    "diffDetected": false
  }
}

diff.detected

{
  "event": "diff.detected",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "scheduleId": "uuid",
    "scheduleName": "Example Monitor",
    "url": "https://example.com",
    "screenshotId": "uuid",
    "screenshotUrl": "https://captureze.com/screenshots/...",
    "diffPercent": 5.2,
    "diffImageUrl": "https://captureze.com/screenshots/.../diff.png",
    "previousScreenshotId": "uuid"
  }
}

Headers

Each webhook request includes these headers:

• Content-Type: application/json
• X-Webhook-ID: <webhook-id>
• X-Webhook-Signature: <signature>
• X-Webhook-Timestamp: <unix-timestamp>

Verifying Signatures

To verify that a webhook request came from Captureze, validate the signature:

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

function verifyWebhook(payload, signature, secret, timestamp) {
  const signedPayload = `${timestamp}.${JSON.stringify(payload)}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

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

Retry Policy

If your endpoint returns a non-2xx status code, we'll retry the webhook:

• 1st retry: after 1 minute
• 2nd retry: after 5 minutes
• 3rd retry: after 30 minutes
• 4th retry: after 2 hours
• 5th retry: after 24 hours

After 5 failed attempts, the webhook will be marked as failed. You can view delivery logs in Settings → Webhooks.

Best Practices

• Respond quickly - Return a 2xx status code within 30 seconds
• Process asynchronously - Queue webhook data for background processing
• Verify signatures - Always validate the webhook signature
• Handle duplicates - Use the screenshot ID to deduplicate events
• Use HTTPS - Only HTTPS endpoints are supported