Set up webhook alerts

Integrate Httpeace with your custom tools and workflows by configuring webhook alerts that send HTTP POST requests when domain issues are detected.

Note: Webhook alerts are available on Business and Scale plans. View pricing

Why use webhooks?

Webhooks enable you to:

  • Custom integrations — Connect Httpeace to any tool that accepts HTTP requests
  • Automated workflows — Trigger actions in your systems when issues occur
  • Incident management — Integrate with PagerDuty, Opsgenie, or custom tools
  • Custom notifications — Route alerts to SMS, phone calls, or other channels
  • Data processing — Send alert data to your analytics or logging systems

Creating a webhook

Step 1: Navigate to developers

  1. In the dashboard, go to Developers
  2. Click Create webhook

Step 2: Configure webhook details

Provide a Webhook URL:

  • The endpoint that will receive HTTP POST requests
  • Must be a valid HTTPS URL for security
  • Example: https://your-app.com/webhooks/httpeace

Step 3: Select events

Choose which events trigger webhook requests:

  • report.completed: Fires every time a report is completed, regardless of its findings
  • alert.created: Fires when an alert is generated (for warnings or critical issues)

Note: Webhooks fire for all domains in your workspace.

Step 4: Save and test

  1. Click Create webhook
  2. In the Webhooks table, click on ⋮ and send a test payload to verify your endpoint receives requests
  3. Check your server logs to confirm the test was received

Webhook payload

Alert Created Event

When an issue is detected, Httpeace sends a POST request with this JSON payload:

{
  "event": "alert.created",
  "timestamp": "2024-03-15T10:30:00.000Z",
  "data": {
    "alertId": "alert_abc123",
    "workspaceId": "workspace_xyz789",
    "domainName": "example.com",
    "checkType": "ssl_expiry",
    "severity": "critical",
    "remediation": "Renew your SSL certificate immediately to avoid service disruption.",
    "details": "What we found:\nYour SSL certificate expires in 7 days (expires: March 22, 2024).\n\nWhy it matters:\nAn expired SSL certificate will cause browsers to show security warnings to your visitors, potentially blocking access to your site and damaging trust.",
    "reportUrl": "https://httpeace.com/dashboard/reports/report_def456"
  }
}

Field descriptions:

  • remediation — Action required to resolve the issue
  • details — Detailed explanation with "What we found" and "Why it matters" sections

Report Completed Event

When a domain report finishes (manual or automated), you receive:

{
  "event": "report.completed",
  "timestamp": "2024-03-15T10:30:00.000Z",
  "data": {
    "domainName": "example.com",
    "reportUrl": "https://httpeace.com/dashboard/reports/report_def456",
    "triggerType": "automated",
    "okChecks": 12,
    "warningChecks": 2,
    "criticalChecks": 1,
    "failedChecks": 0
  }
}

Event types

  • alert.created — New issue detected during checks
  • report.completed — Domain health report finished running

Check severity levels

  • ok — Check passed successfully
  • warning — Minor issue, should be addressed
  • critical — Serious issue requiring immediate attention
  • failed — Check couldn't complete (usually connectivity issues)

Verifying webhook signatures

Protect your webhook endpoint by verifying the signature included in requests.

Signature headers

Httpeace includes these headers with each request:

X-Webhook-Signature: abc123def456...
X-Webhook-Timestamp: 2024-03-15T10:30:00.000Z

Verification example (Node.js)

const crypto = require('crypto');

function verifyWebhook(payload, signature, timestamp, secret) {
  // The signature is computed over: timestamp.payload
  const signedPayload = `${timestamp}.${payload}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  return expectedSignature === signature;
}

// In your webhook handler
app.post('/webhooks/httpeace', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
  const payload = JSON.stringify(req.body);
  const secret = process.env.HTTPEACE_WEBHOOK_SECRET;

  if (!verifyWebhook(payload, signature, timestamp, secret)) {
    return res.status(401).send('Invalid signature');
  }

  // Optional: Reject old webhooks (prevent replay attacks)
  const webhookAge = Date.now() - new Date(timestamp).getTime();
  if (webhookAge > 5 * 60 * 1000) {
    // 5 minutes
    return res.status(401).send('Webhook too old');
  }

  // Process the webhook...
  res.status(200).send('OK');
});

Webhook delivery and retries

Delivery expectations

  • Webhooks are sent within seconds of event occurrence
  • Timeout after 10 seconds if your endpoint doesn't respond
  • Expect to receive webhooks in any order

Retry logic

If delivery fails, Httpeace automatically retries with exponential backoff:

  • Retry 1: After 1 second
  • Retry 2: After 2 seconds
  • Retry 3: After 4 seconds

After 4 failed attempts (1 initial + 3 retries), delivery is abandoned and marked as failed.

Note: 4xx client errors (400-499) are not retried, as these indicate a problem with your endpoint configuration.

Handling failures

View delivery failures:

  1. Go to Webhooks page
  2. Click on the webhook name
  3. View Delivery History
  4. See timestamps, status codes, and error messages

Best practices

1. Respond quickly

Return a 200 OK response immediately:

  • Don't perform long-running operations in your webhook handler
  • Queue the work asynchronously
  • Process the webhook payload in a background job

2. Handle duplicates

Webhooks may occasionally be delivered more than once:

  • For alert.created events: Use data.alertId to deduplicate
  • For report.completed events: Use the combination of data.domainName and timestamp
  • Store processed webhook IDs in your database
  • Design your webhook handler to be idempotent

3. Secure your endpoint

Protect your webhook URL:

  • Always verify the signature
  • Use HTTPS (required)
  • Don't expose sensitive information in error responses
  • Rate-limit webhook requests if needed

4. Monitor webhook health

  • Set up alerts if webhook deliveries fail consistently
  • Review delivery history regularly
  • Test webhooks after making changes to your endpoint

Common integrations

PagerDuty

Send domain alerts to PagerDuty:

  1. Create a webhook in Httpeace
  2. Set URL to your PagerDuty Events API endpoint
  3. Transform Httpeace payload to PagerDuty format in a middleware service

Custom Slack notifications

For more control than the built-in Slack integration:

  1. Create a Slack incoming webhook URL
  2. Add it as an Httpeace webhook
  3. Transform payloads to Slack message format

SMS alerts via Twilio

Receive critical alerts by text message:

  1. Create a webhook pointing to your server
  2. In your webhook handler, call Twilio API for critical alerts
  3. Filter by data.severity === "critical" to avoid alert fatigue

Troubleshooting

Webhooks not being received:

  1. Verify webhook is enabled in Httpeace
  2. Check that your endpoint URL is correct and accessible
  3. Ensure your server responds with 200 OK
  4. Review delivery history for error details

Signature verification failing:

  • Confirm you're using the correct secret
  • Verify you're computing the signature on the raw request body
  • Check that the signature algorithm matches (HMAC-SHA256)

Receiving duplicate webhooks:

  • This is normal behavior for reliability
  • Implement idempotency using data.alertId (for alert.created events)
  • Don't rely on webhooks being delivered exactly once

Next steps

Choose the right plan

Ensure you have the features and limits you need for your use case.

Read the guide

Run a typosquat audit

Protect your brand by identifying lookalike domains.

Read the guide

Understand domain reports

Learn how to interpret the data you receive via webhooks.

Read the guide

Previous: Set up Slack alertsNext: Choose the right plan