Alert Webhooks

Receive real-time notifications when alerts are triggered. ParseBounce sends signed webhook requests to your endpoint.

Webhook Payload

When an alert is triggered, ParseBounce sends a POST request to your webhook URL with the following JSON payload:

{
  "alertName": "High Bounce Rate",
  "alertType": "bounce_rate",
  "projectId": "prj_abc123xyz",
  "projectName": "My SaaS App",
  "value": 5.23,
  "threshold": 5,
  "triggeredAt": "2026-01-20T14:30:00.000Z",
  "incidentId": "inc_xyz789",
  "dashboardUrl": "https://parsebounce.com/dashboard?project=prj_abc123xyz",
  "summary": "Bounce rate is 5.23% (threshold: 5%) across 150 messages",
  "affectedDomains": ["gmail.com", "yahoo.com", "hotmail.com"],
  "messageCount": 150
}

Payload Fields

alertName — Name of the alert rule that triggered

alertType — Type: bounce_rate, complaint_rate, any_complaint, any_hard_bounce

projectId — Your project ID

projectName — Human-readable project name

value — Current metric value that triggered the alert

threshold — Configured threshold for this alert

triggeredAt — ISO 8601 timestamp

incidentId — Unique incident identifier

dashboardUrl — Direct link to your dashboard

summary — Human-readable description of the alert

affectedDomains — Top 5 domains affected (bouncing or complaining)

messageCount — Number of messages in the evaluation window

Signature Verification

All webhook requests are signed using HMAC-SHA256. You should verify the signature to ensure the request is from ParseBounce.

Headers

X-ParseBounce-Signature — HMAC signature in format sha256=<hex>

X-ParseBounce-Timestamp — Unix timestamp when the request was signed

Content-Type — Always application/json

User-Agent — ParseBounce-AlertChecker/1.0

Finding Your Signing Secret

Your webhook signing secret is available on the Alerts page. Go to Dashboard → Alerts and look for the Webhook Signing Secret section at the top.

Verification Algorithm

The signature is computed as: HMAC-SHA256(timestamp + "." + body, secret)

Security tip: Always verify the signature before processing webhooks. Also check that the timestamp is within 5 minutes to prevent replay attacks.

Verification Examples

import { createHmac, timingSafeEqual } from 'crypto';

const WEBHOOK_SECRET = process.env.PARSEBOUNCE_WEBHOOK_SECRET!;
const MAX_AGE_SECONDS = 300; // 5 minutes

function verifyWebhook(
  body: string,
  signature: string,
  timestamp: string
): boolean {
  // Check timestamp to prevent replay attacks
  const ts = parseInt(timestamp, 10);
  const age = Math.floor(Date.now() / 1000) - ts;
  if (age > MAX_AGE_SECONDS) {
    console.error('Webhook timestamp too old');
    return false;
  }

  // Compute expected signature
  const signaturePayload = `${timestamp}.${body}`;
  const expectedSignature = createHmac('sha256', WEBHOOK_SECRET)
    .update(signaturePayload)
    .digest('hex');

  // Extract hex from "sha256=xxx" format
  const providedHex = signature.replace('sha256=', '');

  // Use timing-safe comparison
  try {
    return timingSafeEqual(
      Buffer.from(expectedSignature, 'hex'),
      Buffer.from(providedHex, 'hex')
    );
  } catch {
    return false;
  }
}

// Express.js example
app.post('/webhook/parsebounce', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-parsebounce-signature'] as string;
  const timestamp = req.headers['x-parsebounce-timestamp'] as string;
  const body = req.body.toString();

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

  const payload = JSON.parse(body);
  console.log('Alert received:', payload.summary);

  // Process the alert...

  res.status(200).send('OK');
});

Best Practices

Always verify signatures

Never trust webhooks without verifying the HMAC signature. This prevents attackers from sending fake alerts to your endpoint.

Check timestamp freshness

Reject webhooks with timestamps older than 5 minutes to prevent replay attacks.

Respond quickly

Return a 2xx response within 10 seconds. If you need to do heavy processing, acknowledge the webhook first and process asynchronously.

Handle duplicates

Use the incidentId field to deduplicate webhooks. The same incident may be sent multiple times if your endpoint was temporarily unavailable.

Use HTTPS

Always use HTTPS endpoints to ensure webhook payloads are encrypted in transit.

Slack Integration

ParseBounce webhooks are compatible with Slack incoming webhooks. Simply paste your Slack webhook URL when creating an alert rule.

Note: Slack doesn't verify signatures, so you can use the webhook URL directly. For custom integrations that require signature verification, use the examples above.

← Tracking ID MCP Server →