feat(hubspot): expand webhook trigger catalog to 23 slugs

@anshugarg15checks n/achecks…feat/hubspot-webhook-trigger-catalog → master40 files · +1588 −258updated 3w ago

▸Description

Description

Expands HubSpot's webhook trigger catalog from 2 slugs (HUBSPOT_CONTACT_CREATED, HUBSPOT_DEAL_STAGE_UPDATED) to 23 customer-facing slugs covering the full standard CRM object family + conversations inbox. Adds the missing app_level WebhookSpec (`apps/hubspot/trigger-config.ts`) so HubSpot triggers flow through Apollo's V2 setup_fields-based credential model, matching the Slack pattern.

What's new (21 trigger classes)

Family	New triggers
Contacts	Deleted, PropertyChanged
Companies	Created, Deleted, PropertyChanged
Deals	Created, Deleted, PropertyChanged
Tickets	Created, Deleted, PropertyChanged
Line items	Created, Deleted
Products	Created, Deleted
Quotes	Created, Deleted
Conversations	Created, Deleted, NewMessage, PropertyChanged

Existing `HUBSPOT_CONTACT_CREATED` and `HUBSPOT_DEAL_STAGE_UPDATED` keep their slugs, payload shape, and behavior for back-compat with shipped `trigger_instances`.

Design landings

Standard properties only — no custom properties on this catalog. The `*_PROPERTY_CHANGED` triggers accept a free-form `property_name` validated at setup via HubSpot's `hubspotDefined` flag. Custom properties get rejected with a clear error message pointing to the standard-property docs. Rationale: a marketplace app's 1,000 subscription cap is shared across thousands of customers; allowing arbitrary custom property names would exhaust it. The standard catalog (~525 properties total across all object types) is bounded regardless of customer count.

No hardcoded allowlist. HubSpot's per-portal API is the source of truth. Tier differences (Marketing/Sales/Service Hub specific properties) and future HubSpot-added standard properties work without code changes.

Credentials flow (Slack pattern). App-level webhooks need `client_secret` (HubSpot reuses it as the HMAC key — unusual; most providers issue a distinct signing secret), numeric `app_id`, and the developer-account `hapikey`. These are now declared as `setup_fields` in `trigger-config.ts` → stored encrypted on `webhook_endpoints.encryptedData` per project → merged into the `auth` dict by Apollo and read by Mercury via `auth["app_id"]` / `auth["developer_api_key"]`. Existing trigger_instances with legacy config keep working via `_resolve_app_credentials`' config fallback.

No silent polling fallback. If a customer wants something this catalog doesn't cover (custom properties, form submissions, list membership), they get an explicit error pointing to HubSpot's docs — never a stealth downgrade to polling.

Catalog research (cross-platform)

Source	Coverage	Notes
Zapier	7 instant webhook triggers, all backed by `/webhooks/v3/`	+ 16 polling triggers; their property-change triggers all single-property-per-Zap; `form.submission` uses an internal HubSpot mechanism unavailable to third parties
Pipedream	~25 sources, all polling	No webhook sources for HubSpot at all — useful as a use-case coverage cross-check
n8n	16 webhook event types via `HubspotTrigger.node.ts`	Same one-trigger-per-object + single-property selector shape Composio adopts
HubSpot docs	All eventType strings + payloads confirmed verbatim	v3 webhook subscriptions API; same envelope works on v4 (`POST /webhooks/v4/subscriptions`) but v4 is BETA + access-gated

Out of scope this iteration (deferred, not blocked):

`*.privacyDeletion` — GDPR permanent deletes; identical authz to `.deletion`
Custom object events — needs `objectSchema` config field
`.merge` / `.restore` / `*.associationChange` — first-class on v4 only
`form.submission` and `contact.list_membership_*` — no public HubSpot webhook surface exists; Zapier uses internal channels

Webhook + signature versions

Webhook subscriptions API: v3 (`POST /webhooks/v3/{app_id}/subscriptions?hapikey=...`). v4/journal API is BETA + access-gated as of 2026-05; same eventType strings + payload envelope work on both, so v4 migration is auth + base URL only.
Signature: `X-HubSpot-Signature-v3` (HMAC-SHA256 of `method + uri + body + timestamp`, base64, reject timestamps > 5 min old). v3 signature is decoupled from v3 webhooks API — both v3 and v4 webhook payloads use v3 signature.

Files

`apps/hubspot/trigger-config.ts` — new WebhookSpec (signature + setup_fields)
`apps/hubspot/triggers/base.py` — refactored: `HubspotBaseTrigger` reads `app_id`/`developer_api_key` from auth dict (Slack pattern); adds property validation via `hubspotDefined`; supports back-compat fallback for legacy trigger_instances
`apps/hubspot/triggers/init.py` — new (empty marker)
21 new trigger class files in `apps/hubspot/triggers/`
`apps/hubspot/triggers/contact_created_trigger.py` + `deal_stage_trigger.py` — migrated to new base, preserving payload shape and slug
`apps/hubspot/tool.py` — registers all 23 triggers in `triggers()`

How did I test this PR

All Python files compile (`python3 -m py_compile`).
Imports + Pydantic models verified locally against mercury's venv (`Hubspot` class loads with all 23 triggers registered, generic class parameterization resolves correctly).
`ruff check` and `ruff format` clean on all touched files.
Live HubSpot API contracts verified earlier in design phase via the staging `connected_account ca_AaU-5wQs9nRX` (introspection endpoint, `/crm/v3/properties/{type}/{name}` schema with `hubspotDefined`).
Real-traffic payload capture across all 23 events is deferred to Stage 3 e2e using the `webhook-trigger-e2e-testing` skill. Composio's API redacts access tokens at the response boundary (correct security posture), so end-to-end webhook delivery validation needs to happen via Composio's tool execution surface — tracked separately. Code is structurally sound and matches HubSpot's documented payload shape verbatim.
No hermes changes needed — Apollo's existing setup_fields → auth-dict pipe (used by Slack) handles HubSpot's three credentials uniformly.

🤖 Generated with Claude Code

loading diff…