Webhooks

Overview

Webhooks allow your application to receive real-time notifications when events happen on the Stellar Intel platform — such as intent settlements, dispute updates, or reputation score changes — without polling.

Event Types

Payload Format

Webhooks are delivered via HTTP POST to your registered endpoint with the following payload structure:

{
  "event": "intent.settled",
  "id": "evt_abc123",
  "createdAt": "2026-07-28T12:00:00Z",
  "data": {
    "intentHash": "abc...",
    "anchorId": "cowrie",
    "corridor": "usdc-ngn",
    "amount": "100.00",
    "status": "completed"
  }
}

Registering a Webhook

To register a webhook endpoint, send a POST request to the admin API:

curl -sX POST https://stellar-intel.vercel.app/api/admin/webhooks \
  -H 'x-admin-key: YOUR_ADMIN_SECRET_KEY' \
  -H 'content-type: application/json' \
  -d '{
    "url": "https://your-app.com/webhooks/stellar-intel",
    "events": ["intent.settled", "intent.failed"],
    "secret": "your-webhook-secret"
  }'

Signature Verification

Each webhook payload is signed with the webhook secret using HMAC-SHA256. The signature is sent in the X-StellarIntel-Signature header. Verify it to ensure the payload came from Stellar Intel:

// TypeScript verification example
import { createHmac, timingSafeEqual } from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  try {
    return timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expected)
    );
  } catch {
    return false;
  }
}

Best Practices

• • Respond with 200 OK within 5 seconds to acknowledge receipt
• • Return a 4xx status to signal a permanent failure (we will disable the webhook)
• • Return a 5xx or timeout for automatic retry (up to 3 times with exponential backoff)
• • Store the raw payload and verify the signature before processing
• • Idempotency: process by event.id to handle duplicate deliveries