Documentation
DocumentationDeveloperAcademyCommunitySupportLogin
Start typing to search…

Webhooks Triggers

🚧

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 enable your ambient agents to respond to events from your applications 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 activate one or more plugins to execute your process.

📘

Who is this for? Builders seeking always-active automations triggered by system events, such as "New GitHub issue opened," "Offer letter signed," or "Gong call ended," rather than user reactive prompts. (See System Triggers Overview for the full landscape.)

How it works (at a glance)

  1. Provider → Listener. An external application sends a webhook to your Webhook URL, generated when you create a Listener. The Listener is Moveworks' endpoint that captures incoming webhook requests.
  2. Listener → Event. Moveworks authenticates and validates the request, optionally verifies a signature, parses the body and query parameters, and generates an event.
  3. Event → Plugin(s). Matching plugins are evaluated and activated, executing your configured process (actions, approvals, etc.). Observability is provided through dedicated logs.

Key concepts

  • Listener. Moveworks' receiver for webhook requests. Create one per source or reuse across multiple sources, based on your needs.
  • Webhook URL. The unique HTTP endpoint to which your provider sends requests, enabling event creation within Moveworks.
  • Provider vs. Receiver. The provider (e.g., GitHub, Workday, DocuSign) sends webhooks, while 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.

    • Initiating a Conversation from a Webhook trigger

      While you cannot select a conversational process in the plugin body directly even with "advanced" webhooks, you can still initiate a conversation or collect additional input from a user. To do this, you must use a Compound Action as the Body of the Webhook based System Plugin that includes a notify key.

      The notify key allows your plugin to proactively send a message to a user, which can include buttons to start a conversational flow.

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 to allow Moveworks to confirm the request originates from your provider.
  • Auth header. Require a bearer token or API key in the request header.
  • Not in the initial version: mTLS, asymmetric keys, JWKs, or 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: Drop irrelevant events at the entry point (e.g., accept only 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

  • Handle challenge or 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

Trace any event end-to-end with three new log types:

  • listener.webhook.trigger: Confirms the raw request reached your Listener, including headers, method, parsed body, and timestamps.
  • listener.webhook.processor.update: Displays the processing outcome (published, failed with reason, or debounced) and the normalized payload.
  • listener.webhook.plugin.trigger: Indicates which plugins were evaluated, activated, skipped, failed, or expired (TTL).

See the Webhook Logs & Troubleshooting guide for playbooks on diagnosing issues such as "Why didn't my plugin run?"

What to do next

Appendix (glossary)

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

Updated about 5 hours ago