Building Integrations with SAVHN

This guide covers the practical patterns for connecting external systems to SAVHN, once you're authenticated (see Developer Portal Overview) and familiar with the API domains (see API Reference).

Two integration directions

Most integrations fall into one of two shapes, and many real integrations use both together:

1. Inbound — an external system writes into SAVHN (e.g. a marketing site posts new leads into CRM, an e-commerce platform creates Finance invoices).
2. Outbound — SAVHN notifies an external system when something happens inside it (e.g. push a Slack message when a Ticket is escalated, sync a new Employee record to a payroll processor).

Outbound notification is where webhooks come in — rather than polling SAVHN's API on a schedule, you register a URL that SAVHN calls when a relevant event occurs.

The webhook pattern

1. From Developer Portal → Webhooks, register an endpoint URL you control, and select which event types it should receive (e.g. ticket.created, invoice.paid, employee.onboarded, deal.stage_changed).
2. SAVHN sends an HTTP POST to your endpoint when a matching event occurs, with a JSON payload describing the event and a signature header your endpoint can use to verify the request genuinely originated from SAVHN.
3. Your endpoint should respond quickly with a 2xx status to acknowledge receipt. If your endpoint is slow or unreachable, SAVHN retries delivery with backoff for a bounded period before marking the delivery as failed.
4. Failed deliveries and their response codes are visible from Developer Portal → Webhooks → [endpoint] → Delivery Log, which is the first place to check when an integration seems to have silently stopped working.

Illustrative webhook payload shape

{
  "event": "ticket.status_changed",
  "orgId": "org_7b21d4",
  "occurredAt": "2026-07-30T09:14:22Z",
  "data": {
    "ticketId": "tkt_88af12",
    "previousStatus": "open",
    "newStatus": "resolved",
    "assignedTo": "usr_2f9c1a"
  }
}

This is representative of the general shape used across event types — an event name, tenant context, a timestamp, and a data object scoped to the affected record. Always consult the specific event's schema in the Developer Portal before building a parser against it, since payload fields vary by event type.

Verifying webhook authenticity

Treat any endpoint receiving webhooks as public-facing and verify the accompanying signature header against your registered signing secret before trusting the payload. Never perform a write action purely on the basis of an unverified webhook call.

Common integration scenarios

1. Lead capture from a marketing site or ad platform

• Inbound integration: external form submissions or ad-platform lead forms call POST /api/crm/leads with a bearer token scoped to a CRM-only integration identity.
• Keep this identity's role limited to CRM write access only, following least-privilege — it has no reason to reach HRMS or Finance.

2. Syncing HRMS employee changes to a downstream payroll processor

• Outbound integration: subscribe to employee.created / employee.updated webhook events.
• On receipt, call back into /api/hrms/employees/{id} if you need the full record (webhook payloads are intentionally lean; fetch the full resource when you need more than the event tells you).

3. Ticket escalation notifications into Slack/Teams

• Outbound integration: subscribe to ticket.escalated or ticket.sla_breached events, and have your endpoint translate the payload into a chat message via the target platform's own API.

4. Two-way Projects sync with an external PM tool

• This is the most complex common pattern because it requires reconciling both directions without creating update loops:
  • Inbound: your integration writes changes made in the external tool to /api/projects/tasks/{id}.
  • Outbound: a task.updated webhook notifies your integration of changes made inside SAVHN.
  • To avoid infinite sync loops, tag or timestamp writes your integration makes so it can recognize and skip its own echoed webhook event.

5. Automations module vs. custom integration

Before building a custom integration, check whether the Automations module already covers the scenario with a no-code trigger-action builder (e.g. "when a Deal reaches Closed Won, create a Project"). Automations run entirely within SAVHN and don't require API credentials at all — reserve custom integrations for connecting to genuinely external systems.

6. Document generation and Client Portal sharing

• Some organizations integrate an external document-generation tool (e.g. for contracts or proposals) that creates the file externally, then uploads it into SAVHN via POST /api/documents and links it to the relevant Project or Deal record.
• If the intent is external visibility, combine this with a Client Portal share so the generated document appears automatically in the client's portal view rather than requiring a manual share step afterward.

7. Business intelligence exports

• Read-heavy integrations (e.g. feeding an external BI tool) should prefer paginated list endpoints on a schedule appropriate to how fresh the downstream dashboard needs to be, rather than an aggressive polling interval that mostly returns unchanged data.
• Where a module exposes a Reports API surface, prefer pulling a pre-aggregated report result over reconstructing the same aggregation client-side from raw records — it's both faster and less likely to drift from what users see in-product.

Choosing between Automations, webhooks, and a custom integration

It's worth being deliberate about which mechanism fits a given scenario:

Mechanism	Use when
Automations (no-code, inside SAVHN)	The entire trigger and action stay within SAVHN's own modules
Webhooks + your own service	SAVHN needs to notify an external system of something that happened
Direct API calls from an external system	An external system needs to create or update records inside SAVHN
A combination of webhooks and API calls	Genuine two-way sync between SAVHN and an external system

Defaulting to the simplest mechanism that satisfies the requirement keeps the integration surface easier to maintain — reach for a custom webhook-driven service only once you've confirmed Automations can't cover the scenario.

Testing integrations before production traffic

Before pointing a new integration at real business data, work through this sequence:

1. Build and test entirely against a staging organization and staging credentials (see Deployment & Environments Overview), never production, for the initial development cycle.
2. Exercise both the happy path and the failure paths deliberately — an expired token, a malformed payload, a 409 conflict on a duplicate record — and confirm your integration handles each without crashing or silently dropping data.
3. For webhook-driven integrations, use the Developer Portal's delivery log to confirm payloads are arriving in the shape you expect before wiring up the downstream logic that acts on them.
4. Only after a clean staging run should you generate production credentials and repeat a smaller-scale smoke test in production before enabling full traffic.

Reliability guidance

• Idempotency: design inbound write operations to be safely retryable — network retries on your side, or SAVHN's own retry behavior, should not create duplicate records. Where the target endpoint supports an idempotency key or external-reference field, use it.
• Backfill vs. real-time: webhooks tell you about events going forward from the moment you subscribe; they are not a substitute for an initial backfill. For historical data, page through the relevant list endpoint once (e.g. GET /api/crm/leads?page=1) before relying on webhooks for ongoing sync.
• Least privilege: create a dedicated API credential per integration rather than reusing a human admin's token, so you can revoke and audit each integration independently.
• Monitor delivery health: check the webhook delivery log periodically, especially after any change to your endpoint's infrastructure (new domain, cert rotation, load balancer change).

Where to go next

• The API Reference page has the full domain catalog and REST conventions used across every endpoint.
• If you're integrating with an Industry Cloud-specific workflow, its endpoints follow the same auth and conventions as the core domains, scoped under that industry's own API path.