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

Payout Events (bank deposits)

Receipt Events

Payment Schedule Events

Document Intelligence Events

Entity Events

Project & Other Events

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"
  }
}

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.