Webhooks Guide

Overview

Webhooks notify your server in real-time when events occur on your IPLoop account.

Supported Events

Event	Description
usage.threshold	Bandwidth usage exceeds a configured threshold
usage.depleted	Bandwidth balance reaches zero
payment.success	Payment processed successfully
payment.failed	Payment attempt failed
key.created	New API key generated
key.revoked	API key deactivated

Setup

1. Go to the Webhooks page in your dashboard
2. Click Add Webhook
3. Enter your endpoint URL (must be HTTPS)
4. Select the events you want to receive
5. Save — you'll receive a signing secret

Payload Format

{
  "event": "usage.threshold",
  "timestamp": "2026-02-27T10:30:00Z",
  "data": {
    "customer_id": "abc123",
    "usage_gb": 8.5,
    "threshold_gb": 8,
    "plan": "Starter"
  }
}

Signature Verification

Every webhook includes an X-IPLoop-Signature header. Verify it to ensure authenticity:

Node.js

const crypto = require("crypto");

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(JSON.stringify(payload))
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Python

import hmac, hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Retry Policy

If your endpoint returns a non-2xx status code, IPLoop retries:

• 1st retry: after 1 minute
• 2nd retry: after 5 minutes
• 3rd retry: after 30 minutes
• After 3 failures, the webhook is marked as failing