API & Webhooks — Programmatic Integration Guidance

This article documents programmatic integration points and recommended webhook/API patterns for integrating CJH with other systems (ERP, CRM, dispatch tools). It includes security and reliability best practices.

Existing server-side functions

• CJH uses a server-side function to perform address geocoding for properties; the Property Dialog calls a mapbox-geocode function and the server returns lat/lng coordinates. This shows the pattern of delegating sensitive or rate-limited API calls to server-side functions rather than calling third-party APIs directly from the client. :contentReference[oaicite:32]{index=32}

API patterns to provide

If you expose or consume APIs for CJH, consider offering:

• REST endpoints or a GraphQL API for CRUD operations (jobs, clients, properties, invoices, payments).
• Webhooks for event-driven integrations (job.created, job.updated, invoice.paid, payment.received, property.created, inspection.submitted).

Example webhook events

• job.created

Payload (example):

  {
    "event": "job.created",
    "timestamp": "2026-01-01T12:00:00Z",
    "org_id": "org_abc",
    "job": {
      "id": "job_123",
      "job_no": "J-123",
      "title": "Replace sink",
      "property": { "id": "prop_456", "address1": "123 Main St", "lat": 40.123, "lng": -74.123 },
      "status": "new",
      "assigned_to": "tech_789"
    }
  }

• invoice.paid — include invoice number, amount, payment method, and linked job/estimate ids.

Webhook design & reliability

• Authentication: Sign webhooks using an HMAC signature (using a tenant-specific secret) and include the signature in an HTTP header. On delivery, the receiver validates the signature.
• Retries: Implement exponential backoff with a finite retry window (e.g., retry for up to 24 hours). Include an X-Retry-Count header so receivers can detect duplicates.
• Idempotency: Include an idempotency key or a unique event id so receivers can deduplicate events.
• Delivery report: Offer an admin UI to view webhook delivery status and logs for debugging.

Security & best practices

• Tenant secrets: Keep webhook signing keys and third-party API keys in server-side secrets (Vault or cloud secret store). Never embed secrets in the frontend.
• Least privilege: When creating integration service accounts, grant only necessary scopes (read/write as required).
• Logging: Log webhook deliveries, response codes, and payload hashes for audits and debugging.

Example server-side function pattern (geocoding)

• The repo demonstrates a serverless function pattern (e.g., mapbox-geocode) invoked from the client to perform Mapbox geocoding. Use this pattern for any integration requiring a secret token or a rate-limited third-party call.[](https://github.com/thejdmckinney/job-flow-hub-71/blob/main/src/components/properties/PropertyDialog.tsx)

PropertyDialog

Where to document & how to onboard integrators

• Provide a developer portal or API documentation with:
• • Endpoint references and request/response examples.
  • Webhook event catalog and sample payloads.
  • Security requirements (HMAC header name, signing algorithm).
  • Rate limits and recommended retry semantics.

Updated on: 10/01/2026