Appearance
Common Webhook
The unified post-call webhook system at pages/api/responder/common/workflow.ts plus the per-CRM dispatch under lib/workflow/stages/. This section is the canonical knowledge surface for understanding the system and executing CRM migrations onto it.
Unsolicited Opinion
This section exists because CRM migrations are a primary FDE workstream. Right now there are 9 CRMs on the legacy per-CRM webhook system that need to migrate onto this one. The work is mechanical but the surrounding system has enough sharp edges that knowing the four-layer mental model (HTTP entry → durable queue → triager lifecycle → CRM dispatch) is the difference between a migration that takes half a day and one that takes a week of debugging mysterious symptoms.
The tension preserved here: ship migrations fast in the existing brittle adapter shape, while accumulating improvement arguments in the future-brief. The migration playbook documents the brittle shape verbatim. The future-brief accumulates structured observations across migrations for "running up the flagpole."
Reading order
| You want to... | Read |
|---|---|
| Understand how the system works (operator / new FDE / consultant) | Architecture |
| Understand what migrations are migrating from | Legacy comparison |
| Execute a CRM migration | Migration playbook → HouseCall Pro worked example |
| Form an argument about "could be done better" | Future brief |
| See what's still unknown (or add a question) | Open questions |
| See PR #10249 walked through end-to-end | HouseCall Pro |
For deeper context not duplicated in this section:
- The L0-L7 post-call dispatch chain trace:
post-call-dispatch-chain.md - The agent architecture (separate concern from this webhook architecture):
agent-architecture-legacy-vs-current.md - AutoOps-specific stub-wiring solution:
solutions/post-call-runner-crm-dispatch.md
Pages in this section
| Page | What it covers |
|---|---|
| Architecture | The four-layer system: HTTP entry, durable queue, triager lifecycle, CRM dispatch. Vertical/CRM matrix. The four coexisting CRM-dispatch shapes inside HomeServicesWorkflowRunTriager. What you get for free. |
| Legacy comparison | The legacy per-CRM webhook shape. Walking the legacy HCP path. Why the common webhook exists. Migration inventory: 9 CRMs on legacy, 1 in progress (HCP), 1 half-migrated (ACCULYNX), 1 dual-state (OASIS). |
| Migration playbook | Five-step recipe. The four-file booking-<crm>/ package template. The dispatch block template. Per-team rollout. Failure modes. Defensible-PR checklist. When the four-file pattern doesn't fit. |
| Future brief | Running list of "what I'd do differently" observations, each with status field. Updated as Sandy does migrations. PR-ready arguments. |
| HouseCall Pro | PR #10249 walked end-to-end. File-by-file annotated walkthrough. Pre-conditions, smells, open questions. |
Per-CRM pages will be added under crms/ as Sandy works each migration.
Migration status snapshot
| CRM | State | Notes |
|---|---|---|
hcp (HouseCall Pro) | 🚧 In progress | PR AvocaAI/avoca-next#10249 |
acculynx | Half-migrated | Inline branches in booking-triage.ts, no booking-acculynx/ package |
clypboard | Legacy | |
fieldRoutes | Legacy | Likely next ("Field Service") |
iaa | Legacy | |
jobNimbus | Legacy, possibly live-agent-only | No run/handler.ts |
jobber | Legacy | |
pestPac | Legacy | |
servpro / servpro-playwright | Legacy | |
workiz | Legacy | |
oasis | Dual-state | Has both legacy webhook and booking-oasis/ |
albiware | ✅ Migrated | Single-outcome pattern |
autoops, dynamics365, salesforce, salesforce-omnia | ✅ Greenfield | Built on the common webhook |
service_titan | ✅ Migrated (implicit default) | Generic stages |
four_seasons | ✅ Migrated (per-case branch) | Inline rescheduling branch only |
Full inventory and special-state explanations in Legacy comparison.
Conventions used in this section
| Convention | Meaning |
|---|---|
> Blockquote with attribution | Direct quote from production source code or PR description |
::: tip How to read this | Page-level navigation hints |
::: info Unsolicited Opinion | Sandy's interpretation, opinion, or framing — not factual claim |
::: warning | Open questions, footguns, name collisions, sharp edges |
Mermaid diagrams in <FullscreenDiagram> | Mental models, dispatch flowcharts, sequence diagrams |
[obs-N] in future-brief | Numbered observations (cross-referenced from migration-playbook smells column) |
<crm> and <Crm> placeholders | Template placeholders in migration-playbook code blocks; substitute with the actual CRM key/PascalCase |