Webhooks & triggers

A trigger is how Agent A notices that something happened in another app, in real time, without having to keep checking.

When a new contact lands in HubSpot, when someone @mentions you on Slack, when a deal moves stages, Agent A finds out immediately and acts.

What you can do with this

Things teams set up here look like:

• When a new HubSpot contact is MQL, score them against our ICP and post the result to #mql-review.
• When someone @mentions the Slack bot in #pmm-questions, answer in our brand voice.
• When a Linear issue is labeled customer-facing, draft a one-paragraph public summary and DM it to the PMM lead.
• When a GitHub release is published, auto-draft a launch email and send to Notion for review.
• When a Fathom meeting wraps, extract action items and add them to Linear.
• When an Apify scraper finishes, kick off the next stage of a pipeline.

You describe the trigger and the action in plain English. The agent sets up the connection, asks for approval once, then it runs on its own.

How it works under the hood

There are two flavors:

• Connector triggers (preferred). A typed subscription to a third-party service. Setup is one call. The platform handles the subscription, the signing secret, the retry logic, and the event queue. Events arrive with a known schema (Slack, GitHub, Linear, HubSpot, Fathom, Apify, and others).
• Ad-hoc webhooks. For services without a built-in connector trigger yet, the agent mints a generic webhook URL, configures the third party to POST to it, and pulls events into the same queue. The cost is a little more parsing work, since the schema is whatever the third party sends.

Either way, the agent picks the right one for you. You don't choose.

How an event flows

1. Third-party service POSTs to a public URL the platform owns.
2. The platform verifies the signature, parses the payload, enriches it (e.g. resolving channel IDs to names for Slack), and pushes it onto an internal queue.
3. A consumer (an app, a job, or the chat agent) polls the queue with a named cursor and processes events.
4. Each event is acknowledged after processing; unacked events get redelivered if the consumer crashes.

Cursors are per-consumer, so a Console app and a job can both watch the same events without stepping on each other.

Reliable vs auto-ack

• Auto-ack (default). Read events; they vanish from the queue immediately. Simple. Fine for "tail the feed, log to a table."
• Manual ack. Read events, process them, then explicitly acknowledge. If processing crashes, the event is redelivered. Use this when the side effect (an email, a database write, a downstream API call) must not be lost.

If you ask the agent for "a reliable workflow," it picks manual ack by default.

Common shapes of ask

"When a new HubSpot contact is created with lifecycle stage = marketingqualifiedlead, score the company against our ICP and post the result to #mql-review."

The agent: 1. Subscribes to the HubSpot contact-created trigger. 2. Writes a small consumer (Console app or job) that pulls the event, calls the ICP scorer, posts to Slack via the Slack connector. 3. Surfaces both the HubSpot subscription approval and the Slack approval if it's the first use of those surfaces.

"When a GitHub issue is labeled pmm-review, draft a one-paragraph customer-facing summary and DM it to me."

"When someone @mentions the Slack bot in #pmm-questions, answer using the brand voice skill."

What you see in the workspace

For every active subscription: - The connector and event type. - The signing secret status. - The public URL (for ad-hoc) or the third-party app config (for connector triggers). - The consumer that reads the queue.

You can pause or revoke a subscription from the workspace UI. Revoking returns 410 to any further inbound POSTs.

Limits and edge cases

• No event is ever "fan-out from chat." Triggers are server-driven. If a chat session is closed, events still arrive and pile up in the queue until a consumer reads them.
• The queue has a retention window. Unread events older than a few days are dropped. If you suspect a consumer was offline, check before you assume an event was missed.
• Public-site consumers are extra-restricted. Site-surface triggers require explicit per-call review (no blanket approval), because a visitor-controlled flow is a fan-out cost risk.
• Signing secrets are stored, never displayed. The agent can use them but cannot read them back.

Under the hood. Inbound events hit nginx → api-proxy → connectors service. The service verifies the signature against the stored signing secret, runs the connector's enrich hook (e.g. Slack's user-ID to user-name resolver), then writes a row into webhook_events. Consumers pull via GET /webhooks/events?cursor=<name> with optional provider and ack parameters. Manual-ack consumers POST back to /webhooks/ack with through_id.