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
- Go to Settings → Webhooks.
- Click Add Webhook.
- Enter your HTTPS URL and choose which events to subscribe to.
- Copy the signing secret — you need it to verify payloads.
Event types
| Event | Trigger |
|---|---|
| NEW_REPORT | A new abuse report is submitted |
| SCORE_CHANGED | An IP's reputation score changes |
| RISK_LEVEL_CHANGED | An IP's risk level changes |
| WHITELISTED | An IP is added to the allowlist |
| REVIEW_TRIGGERED | An 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
FAILEDand 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.