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 ambient agents to respond to events from applications in real time. External systems (the provider) send an HTTP request to the Listener (the receiver). The Listener validates and parses the request into an event, which activates one or more plugins to execute processes.

📘

"Who is this for?

Builders creating always-active automations triggered by system events, such as "New GitHub issue opened," "Offer letter signed," or "Gong call ended." For the full landscape, see System Triggers Overview."

How it works

  1. Provider → Listener. An external application sends a webhook to the Webhook URL, generated when creating a Listener. The Listener captures incoming 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 configured processes (actions, approvals, etc.).

Event Flow Diagram

flowchart LR
    A[Provider sends HTTP request] --> B[Listener receives request]
    B --> C[Authenticate & Validate<br/>Signature, Headers]
    C --> D[Parse Payload<br/>JSON Schema, Fields]
    D --> E[Apply Filters<br/>Event Type, Dedupe]
    E --> F[Generate Event]
    F --> G[Evaluate Plugins<br/>Conditions Match]
    G --> H[Activate Plugins<br/>Execute Actions]
    H --> I[Log Outcomes]

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.

Key concepts

  • Listener. Moveworks' receiver for webhook requests. Create one per source or reuse across sources.
  • Webhook URL. Unique HTTP endpoint for providers to send requests, enabling event creation in Moveworks.
  • Provider vs. Receiver. The provider (e.g., GitHub, Workday, DocuSign) sends webhooks, while Moveworks (your Listener) receives them.

Listener Capabilities

Authentication & security

  • Signature (HMAC) verification - configure a shared secret to allow Moveworks to confirm the request originates from your provider.
  • Auth header - require bearer token or API key.
  • Currently unsupported - 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.

Event filtering

  • Listener-Level Filters: Drop irrelevant events at the entry point (e.g., accept only issues.opened, ignore issues.edited).
  • Supported at listener and plugin levels for 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/CRC requests during provider registration.

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?"

Next Steps

Appendix (glossary)

  • Webhook: Automated notification sent by a provider on an event.
  • Webhook Event (Payload): Data package in the request, typically JSON.
  • Headers: Metadata such as event type, request IDs, or signatures.
  • System Trigger: Non-conversational trigger (e.g., webhook) initiating a plugin.

Updated 15 days ago