> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vorel.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# n8n

> Around-the-brain workflow templates that consume Vorel's public API and webhooks. Operator-deployed; tenant-isolated by per-tenant API keys.

[n8n](https://n8n.io) is the operator-editable visual studio for **around-the-brain** workflows:
post-booking confirmations, lead-nurture cadences, weekly QA digests. The synchronous AI brain
(router → sub-agent → tools) runs in-code; n8n handles the asynchronous, cross-conversation,
operator-editable layer.

<Note>
  **n8n is optional and operator-run**: it stands up in its own container, separate from the agent
  hot path, behind operator-only SSO. It is not currently running at a public URL. The around-the-brain
  templates are available as importable workflow exports; the operator builds the real workflow in
  the n8n UI per-tenant during onboarding using these as a node-graph reference. Standing up the n8n
  service per-tenant follows the operator setup runbook.
</Note>

## The 3 v1 templates

### Post-booking confirmation

**Trigger:** Vorel webhook on `booking.created`.

**What it does:** When the agent books an appointment, the workflow verifies the webhook HMAC,
re-reads the full appointment from the Vorel API, then fans out: Slack notify the assigned user,
push to the tenant's CRM, schedule a 24-hour-before reminder via Vorel's outbound conversation
send.

**Vorel API surface:**

* `GET /v1/appointments/:id` (re-read the full booking from the webhook's `data.booking_id`)
* `POST /v1/crm/create-record` (create the CRM record)
* `POST /v1/conversations/:id/send` (send the 24h-before reminder)

**Status:** Ready to import. Available as an importable workflow template (ask your Vorel operator).

### Lead nurture (3-day)

**Trigger:** n8n schedule trigger, daily 09:00 cron (`0 9 * * *`).

**What it does:** Daily, find leads stale-qualified for 3+ days, send a re-engagement WhatsApp
template via Vorel's outbound conversation send; escalate to human handoff after 7 days.

**Vorel API surface:**

* `GET /v1/leads?status=qualified&stale_for_days=3` (the canonical cohort filter)
* `POST /v1/conversations/:id/send` (re-engagement message)
* `POST /v1/leads/:id/handoff` (escalate after 7 days)
* `PATCH /v1/leads/:id` (mark the nurture state)

**Status:** Ready to import. Available as an importable workflow template (ask your Vorel operator).

### Weekly QA rollup

**Trigger:** n8n schedule trigger, Monday 09:00 cron (`0 9 * * 1`).

**What it does:** Aggregate QA scores + hallucination flags + handoff reasons from the prior
7 days; format the rollup; email or Slack the digest to the operator.

**Vorel API surface:**

* `GET /v1/analytics/weekly-rollup` (the single-snapshot endpoint that returns the entire
  digest payload)

**Status:** Ready to import. Available as an importable workflow template (ask your Vorel operator).

## Validity guarantee

Every shipped template's `httpRequest` URLs are CI-validated against the live OpenAPI spec: a
CI test cross-references each URL against the spec's paths and fails the build on any mismatch. A
renamed or removed Vorel endpoint catches at template-test time, not at operator-import time.

## How operator deployment works

When n8n is stood up, the operator runs through this on each new tenant:

<Steps>
  <Step title="Stand up the n8n service">
    Stand up n8n as its own container per the operator setup runbook.
  </Step>

  <Step title="Gate n8n behind operator SSO">
    Put the n8n domain behind operator SSO so only the operator team (Vorel employees) can reach
    it. n8n is **not** customer-facing.
  </Step>

  <Step title="Issue a per-tenant Vorel API key">
    From `/(dashboard)/settings/integrations/api-keys` (or operator-console issuance for tenants who
    haven't set up their team yet). Pick the minimum scope set the workflows need: - Post-booking
    confirmation: `crm:write` + `conversations:write` - Lead nurture: `read` + `leads:write` +
    `conversations:write` - Weekly QA rollup: `read`
  </Step>

  <Step title="Import the template files">
    Each workflow template imports cleanly into n8n. Configure credentials (the API key) + the cron
    timezone (per the tenant's local time).
  </Step>

  <Step title="Wire webhook subscriptions">
    For webhook-triggered workflows (post-booking-confirmation), wire the Vorel-side webhook
    subscription at `/admin/tenants/[id]/integrations/webhooks` so the right event types POST into
    the right n8n webhook URL.
  </Step>

  <Step title="Test end-to-end">
    Trigger the workflow live (book a test appointment for the post-booking-confirmation flow;
    cron-fire manually for the others). Verify the Slack notification + the CRM record + the
    follow-up message lands as expected.
  </Step>
</Steps>

## Customising templates per tenant

Each template is **deliberately small** (roughly 4–7 nodes) so operators can fork them per-tenant:

* **Per-vertical messaging:** clinic-pack tenants may want a different post-booking copy than
  real-estate tenants. Fork the template, swap the message body, keep the API call shape.
* **Per-tenant escalation channels:** Slack vs. Teams vs. email. Replace the notification
  node, leave the rest.
* **Per-tenant SLAs:** change the cron schedule (daily 09:00 → daily 17:00) per the tenant's
  business rhythm.

The template files are starting points, not the limit.

## Building custom workflows beyond the v1 set

Tenants can request bespoke workflows during onboarding. Common patterns:

* **CRM-side triggers.** Subscribe to `lead.qualified` and pre-populate a downstream system.
* **VIP routing.** Subscribe to `conversation.created` and route VIPs to a specific human
  channel via the customer's `regular_status` lead attribute.
* **Cancellation-recovery.** Subscribe to `booking.cancelled`, wait 1h, send a re-book offer.
* **Capacity alerts.** Cron: count `booking.created` events in the last hour against a
  threshold; alert ops when capacity exceeds expected.

Built against the same `/v1/*` API. Delivered the same way: operator-imported per-tenant.

## Why n8n vs. building it ourselves

We considered three alternatives:

* **In-app workflow editor:** too much surface area for too little payoff at this stage. We'd
  be reinventing what n8n already does well.
* **Pure code (TS workers):** fastest for one-off integrations, but not editable per-tenant
  without a code deploy. Defeats the operator-centric model.
* **Zapier / Make:** strong consumer brands; weaker self-host story; price model gets ugly at
  per-tenant volumes.

n8n landed because it's open-source, self-hostable, has a solid HTTP node, and the workflow
editor is exactly the right abstraction for operators tuning per-tenant flows.

## What's NOT supported

* **Customer-facing workflow editing.** n8n is operator-team-only behind operator SSO.
* **Vorel-managed scheduling.** Crons live in n8n; we don't run a cron service today.
* **Auto-deployment of templates.** Operators import per-tenant manually. Templated provisioning
  is a roadmap item if customer count outgrows the manual flow.

## Related docs

* [Automation](/product/automation): the in-code vs. n8n split
* [API Reference](/api-reference/introduction): the surface n8n consumes
* [Webhooks](/api-reference/webhooks): how `booking.created` etc. fire
* [Authentication](/api-reference/authentication): per-tenant API key issuance

{/* verified-against: handoff/n8n-workflows/*.template.json (3 ready + 1 deprecated whatsapp-turn); post-booking template DOES include a GET /v1/appointments/:id node (registry vorelEndpoints omits it, but the JSON re-reads the booking) */}

{/* verified-against: apps/web/src/app/admin/automation/templates-validity.test.ts (CI gate cross-references httpRequest URLs against lib/openapi-spec.ts) */}

{/* verified-against: handoff/docs/runbooks/n8n-setup.md (operator deployment runbook) */}