Fondo Webhooks & Events

Prerequisites

A signing secret in the secret manager, raw-body validation, event ledger, approved destinations, redaction policy, and synthetic fixtures.

Output

Return opaque event ID, signature result, idempotency outcome, destination status, and redacted error category. Keep financial payloads and credentials out of logs.

Error Handling

Reject invalid signatures, quarantine unknown schemas or destinations, bound retries, and pause downstream processing on access or reconciliation failures.

Examples

Deliver a fictional signed event twice and confirm only the first is processed; reject an invalid signature without logging its payload or forwarding data.

Overview

Fondo itself does not send webhooks. Instead, build event-driven workflows using webhooks from the same providers Fondo connects to: Stripe (revenue), Gusto (payroll), Plaid (bank transactions), and Mercury (banking).

Provider Webhooks

Instructions

Stripe Revenue Webhook

import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_API_KEY!);

app.post('/webhooks/stripe', express.raw({ type: '*/*' }), (req, res) => {
  const sig = req.headers['stripe-signature'] as string;
  const event = stripe.webhooks.constructEvent(
    req.body, sig, process.env.STRIPE_WEBHOOK_SECRET!
  );

  switch (event.type) {
    case 'charge.succeeded':
      const amount = (event.data.object as Stripe.Charge).amount / 100;
      console.log(`Revenue: $${amount}`);
      // Update internal dashboard
      break;
    case 'invoice.paid':
      // MRR tracking
      break;
  }
  res.sendStatus(200);
});

Gusto Payroll Webhook

// Gusto sends webhooks when payroll is processed
app.post('/webhooks/gusto', express.json(), async (req, res) => {
  const { event_type, data } = req.body;

  if (event_type === 'payroll.processed') {
    const totalPayroll = data.totals.gross_pay;
    console.log(`Payroll processed: $${totalPayroll}`);
    // Alert if significantly different from budget
    if (totalPayroll > monthlyPayrollBudget * 1.1) {
      await sendAlert(`Payroll exceeded budget by ${((totalPayroll / monthlyPayrollBudget - 1) * 100).toFixed(0)}%`);
    }
  }
  res.sendStatus(200);
});

Resources

• Stripe Webhooks
• Gusto Webhooks
• Plaid Webhooks

Next Steps

For performance optimization, see fondo-performance-tuning.