IPAbuse Developers

Webhooks

Webhooks send HTTP notifications when supported IP events happen, such as a new report or a reputation score change.

Plan requirements

Webhooks are available on the Professional plan and above. On other plans you can view existing endpoints, but you cannot create or resume them.

If your plan changes to one without webhooks, your endpoints are kept but stop receiving events until you upgrade again. Nothing is deleted.

Configure a webhook

  1. Go to Settings → Webhooks.
  2. Click Add Webhook.
  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

EventTrigger
NEW_REPORTA new abuse report is submitted
SCORE_CHANGEDAn IP's reputation score changes
RISK_LEVEL_CHANGEDAn IP's risk level changes
WHITELISTEDAn IP is added to the allowlist
REVIEW_TRIGGEREDAn IP is flagged for review

Payload shape

JSON
{
  "event": "NEW_REPORT",
  "ipAddress": "1.2.3.4",
  "timestamp": "2025-01-15T10:23:00Z",
  "data": {
    "reportId": "report-id",
    "category": "SPAM",
    "severity": 3
  }
}

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:

TypeScript
import crypto from "crypto";

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

// 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

  • Delivery is best-effort and failed deliveries are not automatically retried. Make event handling idempotent and monitor subscription failures.
  • Each delivery attempt times out after 10 seconds.
  • After 10 consecutive failures, the subscription is marked FAILED and stops receiving events. Fix your endpoint, then resume the subscription in Settings → Webhooks.
  • A response with a 2xx status counts as success. Any other status, and any timeout, counts as a failure.

Next steps

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