Webhook Events

Webhooks send real-time HTTP POST notifications to your server when events occur in ClientCasa. Use them to trigger workflows, sync data, and build custom integrations.

Configuration

Configure webhooks in your dashboard at Settings > Webhooks. For each endpoint you can:

• Set a destination URL that receives POST requests
• Choose which events to subscribe to
• Add a signing secret for HMAC-SHA256 signature verification
• Enable or disable the endpoint without deleting it

Signature Verification

When you configure a signing secret, ClientCasa includes two headers on every delivery for verification:

The signature is computed over {timestamp}.{body}. Verify it like this:

const crypto = require('crypto')

function verifyWebhookSignature(body, timestamp, signature, secret) {
  // Reject old timestamps (> 5 minutes) to prevent replay attacks
  const now = Math.floor(Date.now() / 1000)
  if (Math.abs(now - parseInt(timestamp)) > 300) {
    throw new Error('Timestamp too old')
  }

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${body}`)
    .digest('hex')

  const received = signature.replace('sha256=', '')

  if (
    !crypto.timingSafeEqual(
      Buffer.from(expected, 'hex'),
      Buffer.from(received, 'hex'),
    )
  ) {
    throw new Error('Invalid signature')
  }
}

Event Types

Proposal & Document Events

A proposal is one client-facing page assembled from blocks. These events track it through its lifecycle. (The smart_file_ prefix is ClientCasa's internal name for these documents — subscribe to the literal event strings below.)

Contract Events

These track standalone contracts (sent for e-signature) through their lifecycle.

Invoice & Payment Events

recurring_billing_restarted carries why it fired and the billing status it left the client in (as written, never guessed), so an automation never reports a restart that did not happen:

data also includes client (id, name), contact (the billing contact), retriedInvoices (id, invoiceNumber — what is charged), and the title and message the owner sees.

Sample payload

recurring_billing_restarted names why it fired (cause), the status it left the client in, the client, the billing contact, and the open invoices it charges (invoiceNumber is null for an invoice that has no number yet). title and message are the same words you see in your notifications. retriedInvoices can be empty.

{
  "event": "recurring_billing_restarted",
  "timestamp": "2026-09-24T14:30:00.000Z",
  "data": {
    "cause": "new_card",
    "billingStatus": "active",
    "client": {
      "id": "client_abc123",
      "name": "Rivera Studio"
    },
    "contact": {
      "id": "contact_def456",
      "name": "Jordan Rivera"
    },
    "retriedInvoices": [
      { "id": "inv_ghi789", "invoiceNumber": "INV-0042" }
    ],
    "title": "Automatic billing restarted for Rivera Studio",
    "message": "Jordan Rivera saved a new card, so automatic billing is back on. We’ll try INV-0042 once more on the new card. If it doesn’t go through, billing is suspended — and if the card is declined outright, it waits for a new card."
  }
}

Payout Events (bank deposits)

Receipt Events

Sale Events

A sale is money you took without an invoice first — at a market, a walk-up, or through a connected store. Sale events carry the same fields as invoice events, plus the sale's channel, external ID, tax, and refund details. The buyer is optional, so client and contact are absent on an anonymous sale.

Payment Schedule Events

Document Intelligence Events

Entity Events

Project & Other Events

Messaging Events

Run of Show Events

These track event days (the minute-by-minute schedules behind Run of Show) and their timeline items through the run-up and the day itself.

Sample payloads

event_day_created, event_day_published, and event_day_archived share the same event-day shape:

{
  "event": "event_day_published",
  "timestamp": "2026-03-14T15:30:00.000Z",
  "data": {
    "id": "evd_abc123",
    "name": "Smith Wedding",
    "date": "2026-09-19",
    "status": "published",
    "projectId": "proj_xyz789"
  }
}

timeline_item_completed and timeline_reminder_sent are shaped around the timeline item:

{
  "event": "timeline_item_completed",
  "timestamp": "2026-09-19T21:42:00.000Z",
  "data": {
    "id": "tli_def456",
    "name": "Reception entrance",
    "eventDayId": "evd_abc123",
    "status": "completed"
  }
}

Lead & lifecycle events

A lead is a client at an early lifecycle stage, so the whole lead-to-customer journey is covered by these events (they replaced the older inquiry events).

Payload Format

All webhook deliveries use this envelope format:

{
  "event": "invoice_paid",
  "timestamp": "2026-03-14T15:30:00.000Z",
  "data": {
    "documentType": "invoice",
    "documentId": "inv_abc123",
    "documentNumber": "INV-0042",
    "amount": 2500.00,
    "client": {
      "id": "client_xyz",
      "name": "Acme Corp"
    },
    "contact": {
      "id": "contact_123",
      "name": "Jane Smith",
      "email": "jane@acme.com"
    }
  }
}

The data object varies by event type but always includes identifiers for the relevant resources. Payment-related events include additional fields:

{
  "event": "invoice_paid",
  "timestamp": "2026-03-14T15:30:00.000Z",
  "data": {
    "documentType": "invoice",
    "documentId": "inv_abc123",
    "documentNumber": "INV-0042",
    "amount": 2500.00,
    "client": {
      "id": "client_xyz",
      "name": "Acme Corp"
    },
    "contact": {
      "id": "contact_123",
      "name": "Jane Smith",
      "email": "jane@acme.com"
    },
    "paymentMethod": "card",
    "last4": "4242",
    "brand": "visa"
  }
}

A payment on a closed invoice (invoice_closed_payment_received) adds the payment that arrived and how the invoice was closed, beside the invoice's own fields:

{
  "event": "invoice_closed_payment_received",
  "timestamp": "2026-09-24T18:05:00.000Z",
  "data": {
    "documentType": "invoice",
    "documentId": "inv_abc123",
    "documentNumber": "INV-0042",
    "amount": 600.00,
    "status": "void",
    "client": { "id": "client_xyz", "name": "Acme Corp" },
    "closedPayment": {
      "paymentId": "pay_def456",
      "amount": 600.00,
      "closedAs": "void"
    }
  }
}

Retry Policy

Inbound webhooks

The events above are outbound — ClientCasa delivering notifications to your endpoints. ClientCasa also receives webhooks from the services that power its money, messaging, and signing features:

• Stripe — payment and payout reconciliation (payment intent state changes, charges, disputes, payouts).
• Resend — inbound email replies (routed into your message threads) and delivery feedback (bounces, complaints).
• Firma — e-signature status updates for contracts and agreements.

These inbound integrations are platform-managed and not user-configurable — there is nothing to set up, and they are listed here only so you understand how data flows into your account.