Webhooks

const webhook = await cleavr.webhooks.create({
  url: 'https://yourapp.com/webhooks/cleavr',
  events: [
    'receivable.*',  // All receivable events
    'user.onboarding.completed',
    'payment.received'
  ],
  description: 'Production webhook endpoint'
});

// Response
{
  "id": "wh_a1b2c3d4e5f6",
  "url": "https://yourapp.com/webhooks/cleavr",
  "secret": "whsec_xxxxxxxxxxxxx",  // Save this!
  "events": ["receivable.*", "user.onboarding.completed", "payment.received"],
  "created_at": "2025-08-28T10:00:00Z"
}

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

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

  if (!verifyWebhookSignature(req.body, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);

  // Process event
  processWebhookEvent(event);

  // Always respond quickly
  res.status(200).send('OK');
});

{
  "id": "evt_unique_id",
  "type": "event.type.name",
  "api_version": "2025-08-28",
  "created_at": "2025-08-28T10:00:00Z",
  "data": {
    // Event-specific data
  },
  "metadata": {
    "platform_id": "plat_live_xxx",
    "environment": "production"
  }
}

class WebhookHandler {
  async handleEvent(event) {
    // 1. Acknowledge receipt immediately
    this.acknowledge();

    // 2. Verify this is a new event (idempotency)
    if (await this.isDuplicate(event.id)) {
      return;
    }

    // 3. Store event for replay capability
    await this.storeEvent(event);

    // 4. Process based on event type
    switch (event.type) {
      case 'receivable.payment.received':
        await this.handlePaymentReceived(event.data);
        break;

      case 'receivable.disputed':
        await this.handleDispute(event.data);
        break;

      case 'receivable.payment.partial':
        await this.handlePartialPayment(event.data);
        break;

      // ... other events
    }

    // 5. Mark as processed
    await this.markProcessed(event.id);
  }

  async handlePaymentReceived(data) {
    // Update your database
    await db.invoices.update({
      where: { external_id: data.receivable_id },
      data: {
        status: 'paid',
        paid_amount: data.payment_amount,
        paid_at: data.payment_date
      }
    });

    // Notify your user
    await emailService.send({
      to: user.email,
      subject: 'Payment Received!',
      template: 'payment_received',
      data: data
    });
  }

  async handlePartialPayment(data) {
    // Decide whether to continue recovery
    const decision = await this.evaluatePartialPayment(data);

    // Send decision back to Cleavr
    await cleavr.receivables.handlePartialPayment(data.receivable_id, {
      action: decision.continue ? 'continue_recovery' : 'mark_complete',
      notes: decision.reason
    });
  }
}

// List recent events
const events = await cleavr.webhooks.listEvents({
  since: '2025-08-28T00:00:00Z',
  type: 'receivable.payment.received',
  limit: 100
});

// Replay specific event
await cleavr.webhooks.replayEvent('evt_xyz123');

// Send test webhook
await cleavr.webhooks.sendTest({
  type: 'receivable.payment.received',
  endpoint_id: 'wh_xxx'
});

# Expose local server
ngrok http 3000

# Register ngrok URL as webhook endpoint
# https://abc123.ngrok.io/webhooks/cleavr

# Listen to events
cleavr webhooks listen --forward-to localhost:3000/webhooks/cleavr

# Trigger test event
cleavr webhooks trigger receivable.payment.received \
  --receivable rec_test_123 \
  --amount 1000

const health = await cleavr.webhooks.getHealth('wh_xxx');

// Response
{
  "endpoint_id": "wh_xxx",
  "url": "https://yourapp.com/webhooks/cleavr",
  "status": "healthy",
  "success_rate": 99.8,
  "average_response_time_ms": 145,
  "last_error": null,
  "failed_attempts_24h": 2,
  "successful_attempts_24h": 1847
}

const logs = await cleavr.webhooks.getLogs({
  endpoint_id: 'wh_xxx',
  status: 'failed',  // or 'success'
  since: '2024-01-15T00:00:00Z'
});

Production:
- 34.89.123.45
- 34.89.123.46
- 34.89.123.47

Test:
- 35.90.234.56

POST /webhooks/cleavr HTTP/1.1
Content-Type: application/json
Cleavr-Signature: sha256=xxxxxxxxxxxxx
Cleavr-Event-Id: evt_a1b2c3d4e5f6
Cleavr-Timestamp: 1234567890
User-Agent: Cleavr-Webhooks/1.0

// Generate new secret
const newWebhook = await cleavr.webhooks.rotateSecret('wh_xxx');

// Update your configuration
process.env.WEBHOOK_SECRET = newWebhook.secret;

// Old secret remains valid for 24 hours

// Track receivable state changes
const stateMachine = {
  pending: ['in_process', 'cancelled'],
  in_process: ['payment_received', 'disputed', 'cancelled'],
  payment_received: ['recovered'],
  disputed: ['in_process', 'cancelled'],
  recovered: [],  // Terminal state
  cancelled: []   // Terminal state
};

function handleStateChange(event) {
  const currentState = getReceivableState(event.data.receivable_id);
  const newState = event.data.status;

  if (!stateMachine[currentState].includes(newState)) {
    logWarning(`Invalid state transition: ${currentState} -> ${newState}`);
  }

  updateReceivableState(event.data.receivable_id, newState);
}

// Build recovery timeline
class RecoveryTimeline {
  constructor(receivableId) {
    this.receivableId = receivableId;
    this.events = [];
  }

  addEvent(webhookEvent) {
    this.events.push({
      timestamp: webhookEvent.created_at,
      type: webhookEvent.type,
      data: webhookEvent.data
    });

    this.events.sort((a, b) => new Date(a.timestamp) - new Date(b.timestamp));
  }

  getSummary() {
    return {
      total_contacts: this.events.filter(e => e.type === 'receivable.contact.attempted').length,
      days_to_recovery: this.calculateDaysToRecovery(),
      dispute_occurred: this.events.some(e => e.type === 'receivable.disputed')
    };
  }
}

await cleavr.webhooks.update('wh_xxx', {
  debug_mode: true,  // Logs full request/response
  debug_email: 'platform@yourcompany.com'
});