feat(automations): Circleback trigger provider
Merged
SA
3mo ago+600+600+012345678901234567890123456789-2-2-0123456789
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,isRegexpinned false). - Route:
POST /api/integrations/circleback/webhook/[triggerId]— verifiesx-signature(HMAC-SHA256 hex over the raw body, timing-safe) before parsing, recordsautomation_events(provider="circleback", full body inpayload,title=name,url=https://circleback.ai/meetings/{id}), evaluates the addressed trigger viatriggerMatches, enqueues a run through QStash. - Shared:
circlebackTriggerConfigSchemainautomation-triggers.ts;automation-matching/circleback.ts+ onecaseintriggerMatches(MatchContext.circleback).
Two brief-vs-reality deviations (facts, agreed with the coordinator)
- 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.setTriggerSecretstores it raw inautomation_triggers.secret_hash(never inconfig, which every org member can read; the API never returns the column, onlysecret_prefix). The route 401s until it's set. 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_hashschema comment. - From trigger-provider-google:
ScopeChip.allowCustom. SentenceContext.triggerId(+ 1 line inTriggerSentence.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, attendeeAlice@Example.com, name filterVenue, Save triggers → URL chip appears with the saved trigger id; pasted awhsec_…secret → chip showswhsec_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_hashset. - Replayed Circleback's documented example payload at the route:
- bad / missing
x-signature→ 401 - valid signature, meeting tagged
Sales, attendeealice@example.com, name "Event Venue Review" → 200 matched — log:[circleback/webhook] trigger d79600c1-… matched, enqueuing run for automation 747434f5-…: 80663d01-…;automation_eventsrowprovider=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).
- bad / missing
bun run typecheckin shared/db/trpc/api/desktop: all exit 0.biome checkon every touched dir: exit 0. Rootbun run lintexits 1 only on the pre-existingTerminalAgentAutoResume.tsxa11y 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
circlebackmatcher in@superset/shared/automation-matchingandcirclebackTriggerConfigSchemain@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), andScopeChip.allowCustomfor 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.