Webhook Triggers (Limited Preview)

🚧

Limited Preview: Webhook Triggers & Listener

Webhook Triggers and the Webhook Listener are currently in Limited Preview and may change without notice. Access is invite-only. Self-nomination form is here. Production use is approved but may be subject to interruptions or breaking changes.

Webhook triggers let your ambient agents react to events from your apps in real time. External systems (the provider) send an HTTP request to your Moveworks Listener (the receiver). The Listener validates and parses the request into an event, which can trigger one or more plugins to run your process.

📘

Who is this for? Builders who want always-on automations that start from system events rather than user prompts e.g., “New GitHub issue opened,” “Offer letter signed,” or “Gong call ended.” (See System Triggers Overview for the full landscape.)

How it works (at a glance)

1. Provider → Listener. An external app sends a webhook to your Webhook URL (generated when you create a Listener). The Listener is Moveworks’ endpoint that “listens” for incoming webhook requests.
2. Listener → Event. Moveworks authenticates/validates the request, optionally verifies a signature, parses the body (JSON in LP), and creates an event.
3. Event → Plugin(s). Matching plugins are evaluated and triggered; your configured process runs (actions, approvals, etc.). Observability is available via dedicated logs.

Key concepts

• Listener. Moveworks’ receiver for webhook requests. Create one per source or reuse across sources—your choice.
• Webhook URL. The unique HTTP endpoint your provider posts to; it’s how events are created inside Moveworks.
• Provider vs. Receiver. The provider (e.g., GitHub, Workday, DocuSign) sends webhooks; Moveworks (your Listener) receives them.

What’s in scope in Limited Preview today?

We’re shipping webhook triggers in two waves:

• LP1 (Basic): Ideal for simple notifications, simple approvals (approve/deny), and fully backend automations with little or no user conversation. ~65% of sampled event-driven use cases fit here.
• LP2 (Advanced): Adds richer, multi-turn conversational patterns and branching.

Out of scope: Scheduled triggers and pollers are not part of LP1 or LP2 for webhooks; this project covers real-time event triggers only.

Capabilities at the Listener layer

Authentication & security

• Signature (HMAC) verification – recommended. Configure a shared secret so Moveworks can verify the request originated from your provider.
• Auth header. Require a bearer token or API key in a header.
• Not in the initial version: mTLS, asymmetric keys, JWKs/JWTs.

Why secure? Without auth/signature, anyone who knows your URL can attempt to trigger your workflow. Unsecured listeners are heavily rate-limited (e.g., 1 req / 10s) vs. significantly higher limits for secured listeners.

Payload validation

• Schema validation (JSON). Define the expected structure to validate and extract fields reliably; otherwise the raw request is treated as an unstructured blob downstream.

Event filtering

• Listener-level filters to drop irrelevant events at the door (e.g., only accept issues.opened, ignore issues.edited). Filtering is supported at both the listener and plugin levels for flexibility and reuse.

Deduplication & replay protection

• Prevent duplicate requests from triggering the same plugin twice; logs will show debounced/skipped events.

One-time verification challenges

• Respond to challenge/CRC requests used by providers during webhook registration.

How events become plugin runs

1. Raw request received at your Listener → listener.webhook.trigger.
2. Processed & published (or rejected/debounced) → listener.webhook.processor.update.
3. Plugins evaluated & triggered → listener.webhook.plugin.trigger.
4. Process executes → compound_action.* and action logs.

Platform rules and limitations

• One trigger paradigm per plugin. A plugin can be triggered by system triggers (one or many), or by conversational triggers (one or many)—but not both. Duplicate the plugin if you need both paradigms.
• Multiple plugins per event. A single event can fan-out to multiple plugins if their conditions match.

Logs & observability

Use the three new log types to trace any event end-to-end:

• listener.webhook.trigger — confirms the raw request hit your Listener (headers, method, parsed body, timestamps).
• listener.webhook.processor.update — shows processing outcome (published, failure with reason, or debounced) and the normalized payload.
• listener.webhook.plugin.trigger — which plugins were evaluated, triggered, skipped, failed, or expired (TTL).

See the dedicated Webhook Logs & Troubleshooting guide for “why didn’t my plugin run?” playbooks.

What to do next

• Build your first listener: Follow the Webhook Triggers Quickstart to create a Listener, post a test event, and watch your plugin run.
• Learn to debug fast: Read Webhook Logs & Troubleshooting to understand the lifecycle and common failure modes.

Appendix (glossary)

• Webhook: Automated notification sent by a provider when an event occurs.
• Webhook Event (Payload): The data package sent in the webhook request (usually JSON).
• Headers: Metadata such as event type, request IDs, or signatures.
• System Trigger: A non-conversational trigger that starts a plugin (like a webhook).