Webhooks

Webhooks let you receive real-time HTTP notifications when events happen in IPAbuse — such as a report being verified, an IP's risk level changing, or a credit transaction completing.

Webhooks are available on the Pro plan and above.

Configure a webhook

1. Go to Settings → Webhooks.
2. Click Add Endpoint.
3. Enter your HTTPS URL and choose which events to subscribe to.
4. Copy the signing secret — you need it to verify payloads.

Event types

Payload shape

{
  "event": "report.verified",
  "timestamp": "2025-01-15T10:23:00Z",
  "data": {
    "reportId": "rpt_01HXXX",
    "ipAddress": "1.2.3.4",
    "category": "SPAM",
    "creditsEarned": 10
  }
}

Verifying signatures

Every webhook request includes an X-IPAbuse-Signature header with a sha256=... HMAC of the raw request body. Always verify this before processing the payload:

import crypto from "crypto";

export function verifyWebhook(rawBody: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expected}`),
  );
}

// In your route handler:
// const rawBody = await req.text();
// const sig = req.headers.get("X-IPAbuse-Signature") ?? "";
// if (!verifyWebhook(rawBody, sig, process.env.WEBHOOK_SECRET!)) {
//   return new Response("Forbidden", { status: 403 });
// }

Delivery guarantees

• At-least-once delivery — your endpoint may receive duplicate events.
• We retry up to 5 times with exponential back-off (5 s, 30 s, 2 min, 10 min, 1 h).
• Your endpoint must respond with a 2xx status within 30 seconds.
• After 5 failed attempts the webhook is marked as failing and you are notified by email.

Next steps

• API Reference — manage webhooks via the API.
• Errors — error codes you may see in webhook payloads.