Webhooks & Alerts

Get notified in real time when scores change, thresholds are crossed, or monitored wallets trigger events. No polling required — VIZI pushes events directly to your endpoint.

Supported Events

VIZI webhooks deliver structured JSON payloads for every significant scoring event. Subscribe to the events you care about and ignore the rest.

`score.updated`

Fired whenever a monitored wallet's VIZI Score changes by any amount. The payload includes the previous score, new score, delta, and the factors that changed. This is the most commonly used event type.

`score.threshold.crossed`

Fired when a score crosses a threshold you define. For example, alert when a borrower's score drops below 600. Configure upper and lower thresholds per monitored address.

`monitoring.alert`

Fired for high-priority risk events: liquidation detected, sanctions match, or sudden large balance drop. These alerts include severity levels (info, warning, critical) and recommended actions.

`batch.completed`

Fired when an asynchronous batch scoring job finishes. The payload includes the batch ID, total addresses processed, success and error counts, and a download URL for the results.

Payload Format

All webhook payloads follow a consistent JSON structure with an event ID, type, timestamp, and a data object containing event-specific fields.

{
  "id": "evt_abc123def456",
  "type": "score.updated",
  "created_at": "2026-03-15T14:30:00Z",
  "data": {
    "address": "0x1234...abcd",
    "chain": "ethereum",
    "previous_score": 720,
    "new_score": 695,
    "delta": -25,
    "grade": "B+",
    "factors_changed": [
      {
        "factor": "collateral_health",
        "previous": 0.92,
        "current": 0.71,
        "impact": "negative"
      }
    ]
  }
}

Every payload includes the id field, which is unique and idempotent. If you receive the same event ID twice (due to retries), you can safely ignore the duplicate. Store processed event IDs in your database to implement idempotency.

Signature Verification

Every webhook request from VIZI includes an HMAC-SHA256 signature in the X-Vizi-Signature header. Always verify this signature before processing any event to ensure the payload was sent by VIZI and has not been tampered with.

Python

import hmac
import hashlib

def verify_webhook(payload_body, signature_header, webhook_secret):
    expected = hmac.new(
        webhook_secret.encode('utf-8'),
        payload_body,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(f"sha256={expected}", signature_header)

# In your webhook handler:
is_valid = verify_webhook(
    request.body,
    request.headers['X-Vizi-Signature'],
    'whsec_your_webhook_secret'
)

Node.js

const crypto = require('crypto');

function verifyWebhook(body, signatureHeader, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(`sha256=${expected}`),
    Buffer.from(signatureHeader)
  );
}

Your webhook secret is displayed once when you create a webhook endpoint in your VIZI dashboard. Store it securely — it cannot be retrieved again. You can always rotate your secret, which will invalidate the previous one immediately.

Retry Policy

VIZI expects your endpoint to return a 2xx status code within 30 seconds. If the request fails or times out, VIZI retries with exponential backoff.

Retry Schedule

Attempt 1: Immediate. Attempt 2: After 1 minute. Attempt 3: After 5 minutes. Attempt 4: After 30 minutes. Attempt 5: After 2 hours. Attempt 6: After 8 hours.

Failure Handling

After 6 failed attempts over roughly 10 hours, the event is marked as failed and logged in your dashboard. You can manually retry any failed event from the webhook logs page.

Auto-Disable

If your endpoint fails consistently for 3 consecutive days, VIZI will automatically disable it and send you an email notification. Re-enable it from your dashboard once the issue is resolved.

Delivery Headers

Each request includes X-Vizi-Delivery-Attempt (1-6), X-Vizi-Event-ID, and X-Vizi-Timestamp headers for debugging and idempotency.

Testing Webhooks

Use the VIZI sandbox to test your webhook integration without affecting production data. The sandbox delivers webhook events within 1 second of triggering actions.

# Trigger a test webhook event via the API
curl -X POST https://sandbox.api.vizi.com/v2/webhooks/test \
  -H "Authorization: Bearer vizi_sk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_id": "we_abc123",
    "event_type": "score.updated"
  }'

You can also use the VIZI dashboard to send test events to any registered endpoint. The dashboard shows a real-time log of all webhook deliveries, including request/response headers, body, status code, and latency — making it easy to debug integration issues.

Best Practices

Follow these guidelines to build a reliable webhook integration that handles edge cases gracefully.

Verify Signatures

Always verify the X-Vizi-Signature header using HMAC-SHA256 before processing. Never skip verification, even in development.

Respond Quickly

Return a 200 immediately and process the event asynchronously. Use a queue (SQS, Redis, RabbitMQ) to decouple reception from processing.

Implement Idempotency

Store the id of each processed event. If you receive a duplicate (same ID), skip processing. This prevents double-counting during retries.

Use HTTPS Only

VIZI only delivers webhooks to HTTPS endpoints. Self-signed certificates are not supported. Use a trusted CA certificate in production.

Set Up Your First Webhook

Create a webhook endpoint in your VIZI dashboard or programmatically via the API. Test it in the sandbox before going live.

API Documentation Test in Sandbox