Webhooks

Receive push notifications when reputation scores change. Available on Starter tier and above.

Register a Webhook

POST /api/v1/webhooks
X-API-Key: did_live_...
Content-Type: application/json

{
  "url": "https://your-app.com/webhooks/crowdproof",
  "walletAddressFilter": "0x1234..."
}

Omit walletAddressFilter to receive updates for all addresses.

Save Your Secret

The secret is only returned on creation. Store it securely — you'll need it to verify webhook signatures.

Verify Signatures

Every delivery includes an X-CrowdProof-Signature header (HMAC-SHA256 of the request body):

import crypto from "crypto";

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

Payload Format

{
  "event": "score.updated",
  "timestamp": "2026-02-27T12:00:00Z",
  "data": {
    "address": "0x1234...",
    "category": "DEFI_LENDING",
    "previousScore": 720,
    "newScore": 742,
    "confidence": 0.91,
    "tier": "High"
  }
}

Limits by Tier

Tier	Max Webhooks
Free	0
Starter	3
Growth	10
Enterprise	50

Auto-Disable

Webhooks are automatically disabled after 10 consecutive delivery failures. Re-enable via the portal or by deleting and re-creating the webhook.

Management

# List webhooks
GET /api/v1/webhooks

# Get by ID
GET /api/v1/webhooks/{id}

# Delete
DELETE /api/v1/webhooks/{id}