Caibo Pay | Send Money. Hold USD. Trade Crypto.

Overview

Webhooks allow you to receive real-time notifications when events happen in your Caibo account. Instead of polling the API, Caibo will send HTTP POST requests to your endpoint.

Event Types

Event	Description
`transfer.created`	A new transfer was created
`transfer.completed`	A transfer was successfully delivered
`transfer.failed`	A transfer failed
`account.created`	A new account was created
`account.updated`	An account was updated
`deposit.received`	A deposit was received into your account

Webhook Payload

webhook-payload.json

{
  "id": "evt_1234567890",
  "type": "transfer.completed",
  "createdAt": "2026-03-10T10:05:00Z",
  "data": {
    "object": {
      "id": "tr_1234567890",
      "amount": 100000,
      "currency": "USD",
      "status": "completed",
      "completedAt": "2026-03-10T10:05:00Z"
    }
  }
}

Create a Webhook Endpoint

create-webhook.js

const webhook = await caibo.webhooks.create({
  url: 'https://your-app.com/webhooks/caibo',
  events: [
    'transfer.completed',
    'transfer.failed',
    'deposit.received'
  ]
});

// Save the signing secret securely
console.log(webhook.signingSecret);

Verify Webhook Signatures

Always verify webhook signatures to ensure requests are from Caibo:

verify-webhook.js

import express from 'express';
import CaiboPay from '@caibopay/sdk';

const app = express();
const caibo = new CaiboPay({ apiKey: 'sk_...' });

app.post('/webhooks/caibo',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['caibo-signature'];

    try {
      const event = caibo.webhooks.constructEvent(
        req.body,
        signature,
        process.env.WEBHOOK_SECRET
      );

      // Handle the event
      switch (event.type) {
        case 'transfer.completed':
          console.log('Transfer completed:', event.data.object.id);
          break;
        case 'deposit.received':
          console.log('Deposit received:', event.data.object);
          break;
      }

      res.json({ received: true });
    } catch (err) {
      console.error('Webhook signature verification failed');
      res.status(400).send('Invalid signature');
    }
  }
);

Retry Policy

Caibo will retry failed webhook deliveries with exponential backoff:

• 1st retry: 1 minute after failure
• 2nd retry: 5 minutes after
• 3rd retry: 30 minutes after
• 4th retry: 2 hours after
• 5th retry: 24 hours after

Tip: Return a 2xx status code within 30 seconds to acknowledge receipt. Process the webhook asynchronously if needed.