Overview

Webhooks allow you to receive real-time notifications about events that occur during the ZBD Ramp lifecycle. From session initialization to payment completion, webhooks provide crucial updates about your users’ transactions. ZBD Ramp sends webhook events to your specified endpoint as HTTP POST requests. Each event contains detailed information about what occurred, allowing you to update your systems accordingly.

Webhook URL Setup

Configure your webhook URL when creating a session:
import { initRampSession, QuoteCurrencyEnum, BaseCurrencyEnum } from '@zbdpay/ramp-ts';

const response = await initRampSession({
  apikey: process.env.ZBD_API_KEY,
  email: 'user@example.com',
  destination: 'lightning-address@zbd.gg',
  quote_currency: QuoteCurrencyEnum.USD,
  base_currency: BaseCurrencyEnum.BTC,
  webhook_url: 'https://app.xyz/webhooks/zbd',  // <---- YOUR WEBHOOK URL HERE
  reference_id: 'order-123',
  metadata: {
    userId: 'user-456',
    plan: 'premium'
  }
});

const sessionToken = response.data.session_token;

Event Categories

Webhook events are organized into six main categories:

Session

Widget lifecycle events

Authentication

User verification events

KYC

Identity verification events

Bank

Bank connection events

Payment

Transaction events

Withdrawal

Crypto delivery events

Event Structure

All webhook events follow a consistent structure:
{
  "event": "RAMP_WIDGET.V1.EVENT_NAME",
  "data": {
    "email": "user@example.com",
    "session_id": "sess_abc123xyz789",
    // Event-specific data
    "metadata": {
      // Your custom metadata
    }
  },
  "url": "https://partner.com/webhooks",
  "created_at": "2025-01-18T10:30:00Z"
}

Complete Event Reference

Session Events

Authentication Events

KYC Events

Bank Connection Events

Payment Events

Withdrawal Events

Webhook Implementation

Basic Handler Examples

Here are webhook handler implementations in popular frameworks:
// app/api/webhooks/zbd/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  const event = await request.json();

  // Log the event
  console.log(`Received webhook: ${event.event}`);

  // Handle different event types
  switch(event.event) {
    case 'RAMP_WIDGET.V1.PAYMENT.SETTLED':
      // Update user balance, send confirmation, etc.
      await handlePaymentSettled(event.data);
      break;

    case 'RAMP_WIDGET.V1.KYC.COMPLETED':
      // Update user verification status
      await handleKYCCompleted(event.data);
      break;

    case 'RAMP_WIDGET.V1.WITHDRAWAL.SUCCEEDED':
      // Log successful withdrawal
      await handleWithdrawalSuccess(event.data);
      break;

    default:
      console.log(`Unhandled event type: ${event.event}`);
  }

  // Always respond with 200 OK
  return NextResponse.json({ received: true }, { status: 200 });
}

async function handlePaymentSettled(data: any) {
  // Your payment processing logic
  console.log('Payment settled:', data);
}

async function handleKYCCompleted(data: any) {
  // Your KYC completion logic
  console.log('KYC completed:', data);
}

async function handleWithdrawalSuccess(data: any) {
  // Your withdrawal success logic
  console.log('Withdrawal succeeded:', data);
}

Security Best Practices

Important: Always validate webhook authenticity before processing events.

Webhook Verification

  1. Use HTTPS Only - Always use HTTPS endpoints for webhooks
  2. Verify Signatures - Validate webhook signatures when provided
  3. IP Allowlisting - Restrict webhook access to ZBD IP addresses
  4. Idempotency - Handle duplicate events gracefully
  5. Timeout Handling - Respond quickly (within 5 seconds)

Error Handling

  • Always respond with 200 OK status, even if processing fails
  • Log all webhook events for debugging
  • Implement retry logic for critical operations
  • Use message queues for asynchronous processing

Testing Webhooks

Local Development

Use tools like ngrok to expose your local webhook endpoint:
ngrok http 3000
Then use the ngrok URL as your webhook endpoint during development.

Webhook Testing Checklist

Essential events to handle:
  • ✅ PAYMENT.SETTLED
  • ✅ WITHDRAWAL.SUCCEEDED
  • ✅ PAYMENT.FAILED
  • ✅ WITHDRAWAL.FAILED

Troubleshooting

Common Issues

Next Steps