feat(automations): Circleback trigger provider

Merged
SA
3mo ago
+600-2

Summary

Adds the Circleback trigger provider (kind circleback, tier 0 — no connection, no integration_provider).

  • Event: meeting.completed (Circleback sends one webhook per finished meeting). Sentence: Meeting ended tagged [tags] with attendee [email] named like ["…"] + URL chip + signing-secret chip.
  • Filters: tags / attendees (ScopeChip with free-form entry, case-insensitive match, {mode:"any"} default like GitHub's branches/labels), nameFilter (TextFilterChip, substring, isRegex pinned false).
  • Route: POST /api/integrations/circleback/webhook/[triggerId] — verifies x-signature (HMAC-SHA256 hex over the raw body, timing-safe) before parsing, records automation_events (provider="circleback", full body in payload, title=name, url=https://circleback.ai/meetings/{id}), evaluates the addressed trigger via triggerMatches, enqueues a run through QStash.
  • Shared: circlebackTriggerConfigSchema in automation-triggers.ts; automation-matching/circleback.ts + one case in triggerMatches (MatchContext.circleback).

Two brief-vs-reality deviations (facts, agreed with the coordinator)

  1. Circleback issues the signing secret (whsec_…, shown in its automation editor) and uses it as the HMAC key — so we can't generate-and-show-once, and can't verify from a hash. The row shows the per-trigger URL; the user pastes Circleback's secret into the "Signing secret" chip → automation.setTriggerSecret stores it raw in automation_triggers.secret_hash (never in config, which every org member can read; the API never returns the column, only secret_prefix). The route 401s until it's set.
  2. externalEventId = ${triggerId}:${meeting.id}, not the bare id: the dedup unique is (integration_connection_id NULLS NOT DISTINCT, provider, external_event_id), and the same meeting legitimately reaches every trigger whose URL is configured in Circleback — a bare id would make the second automation never fire.

Shared bits carried byte-identically (first commit) — whichever PR lands first, the other rebases as a no-op

  • From #6586 (trigger-provider-webhook): automation.setTriggerSecret + rotateWebhookSecret + webhookSecret.ts + EndpointChip + secret_hash schema comment.
  • From trigger-provider-google: ScopeChip.allowCustom.
  • SentenceContext.triggerId (+ 1 line in TriggerSentence.tsx) — same text as #6586; the coordinator is landing a consolidated seam on main, I'll rebase onto it.

Verification (CDP against the running dev app, workspace API on :8761, workspace Neon branch)

  • Added the trigger from Add Trigger › Circleback, typed a custom tag Sales, attendee Alice@Example.com, name filter Venue, Save triggers → URL chip appears with the saved trigger id; pasted a whsec_… secret → chip shows whsec_verify…; navigated away and back → all persisted. DB row: config = {"kind":"circleback","tags":{"ids":["Sales"],"mode":"list"},"event":"meeting.completed","attendees":{"ids":["Alice@Example.com"],"mode":"list"},"nameFilter":{"isRegex":false,"pattern":"Venue"}}, secret_prefix = whsec_verify, secret_hash set.
  • Replayed Circleback's documented example payload at the route:
    • bad / missing x-signature → 401
    • valid signature, meeting tagged Sales, attendee alice@example.com, name "Event Venue Review" → 200 matched — log: [circleback/webhook] trigger d79600c1-… matched, enqueuing run for automation 747434f5-…: 80663d01-…; automation_events row provider=circleback, event_type=meeting.completed, external_event_id=d79600c1-…:WRweb12iCBimU6Vo8cD7z, title=Event Venue Review.
    • same delivery again → 200 duplicate (no second row)
    • valid signature, tag Internal → 200 matched:false reason:tags
    • QStash publish itself fails locally (invalid destination url: endpoint resolves to a loopback address) — known local-only limitation, handled like the GitHub route (logged, delivery acknowledged).
  • bun run typecheck in shared/db/trpc/api/desktop: all exit 0. biome check on every touched dir: exit 0. Root bun run lint exits 1 only on the pre-existing TerminalAgentAutoResume.tsx a11y error on main.

Not in this PR

  • No migration (enum values already on main). No new packages.
  • Nothing prevents pasting a non-whsec_ string — Circleback's format isn't enforced by the general mutation; the chip's placeholder says what to paste.

Summary by cubic

Adds a Circleback trigger provider for meeting-completed webhooks. Requests are HMAC-verified, deduped per trigger, and only the addressed trigger dispatches runs; deliveries 401 until a signing secret is set.

  • API: POST /api/integrations/circleback/webhook/[triggerId] verifies x-signature (HMAC‑SHA256 over the raw body) before parsing. Records automation_events with provider="circleback", event_type="meeting.completed", external_event_id="${triggerId}:${meeting.id}" (per-trigger dedupe), then dispatches only to the addressed trigger; duplicate deliveries ack without re‑enqueue and dispatch failures do not fail the delivery.
  • Matching: Adds circleback matcher in @superset/shared/automation-matching and circlebackTriggerConfigSchema in @superset/shared/automation-triggers. Optional filters tags and attendees are case‑insensitive with “any” semantics; nameFilter is a substring match.
  • Desktop: New Circleback provider with sentence UI, EndpointChip (per‑trigger URL), SigningSecretChip (stores Circleback’s whsec_… and shows its prefix), and ScopeChip.allowCustom for free‑form tags/emails.

Rollout

  • Create a Circleback trigger, save, copy the URL into Circleback, then paste the whsec_… into Signing secret. Deliveries return 401 until the secret is set.
  • Deploy API and Desktop together; no DB migration. Ensure QStash configuration is present.

Summary by CodeRabbit

  • New Features

    • Added Circleback meeting-completed automation triggers with filters for tags, attendees, and meeting names.
    • Added configurable webhook endpoints and signing-secret management.
    • Added secure webhook token creation, rotation, and signature validation.
    • Added support for custom scope values in automation settings.
    • Added endpoint display with HTTP method details, copy action, and notifications.
  • Bug Fixes

    • Prevented duplicate meeting events from triggering automations more than once.
    • Improved handling and feedback for invalid requests and dispatch failures.