Webhooks Listener

🚧

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.

A Listener is Moveworks’ receiver for incoming webhook requests. Creating a listener gives you a Webhook URL that external systems can POST to; Moveworks validates the request, turns it into an event, and can trigger one or more plugins.

New to webhooks? Use the Webhook Triggers Quickstart for end-to-end setup and a minimal example. This page focuses on listener capabilities — especially the Advanced Configurations.

Advanced Configurations

Use these controls to harden, scope, and de-noise incoming traffic before it becomes a Moveworks event.

1. Payload Schema

What it does: Validates the structure and types of the incoming body (LP focus: JSON) so requests that don’t match fail fast. Also supports mapping fields for downstream use.

Minimal example schema (GitHub Issues)

Paste in Payload Schema:

{
  "action": "string",
  "issue": {
    "title": "string",
    "html_url": "string",
    "user": { "login": "string" }
  },
  "repository": { "full_name": "string" }
}

Tips

• Start from an actual payload (see Quickstart for how to grab it) and keep the schema minimal— only what your plugins need.

2. Event Filtering

What it does: Drops unwanted requests at the door. Filtering exists at both the listener and plugin levels; use listener-level rules to keep a reusable listener clean.

How it works: Write expressions against the request payload, headers, and query params to decide if Moveworks should create an event. (See more scenarios in Quickstart and Logs.)

Some examples:

A. GitHub — onlyissues.opened in one repo and titles containing “bug”

(action == "opened")
AND (repository.full_name == "acme/widgets")
AND (issue.title.$LOWERCASE() CONTAINS "bug")

Use with the minimal payload above.

B. DocuSign — only fully executed envelopes; Sales contracts ≥ $10k

(event == "EnvelopeSigned")
AND (contract.type == "Sales")
AND ($DECIMAL(contract.value) >= 10000)

Why filter at the listener? Some providers can’t pre-filter events; listener filters eliminate noise and keep downstream config simple.

3. Verification (Security)

Protect the endpoint so only trusted senders can trigger your workflows. Why this matters? Without verification, anyone who knows your URL can attempt to trigger your workflow; unsecured listeners are heavily rate-limited compared to secured ones.

• Signature verification (HMAC) — recommended. Configure a shared secret to verify origin and integrity.
• Auth header — require a bearer/API token header on every request.

Rate limits: Unsecured listeners are heavily rate-limited (e.g., 1 req / 10s) vs. much higher limits for secured listeners. Secure your listener before production.

4. Redaction (Logs)

Redact secrets and PII from webhook logs. Use this to hide auth headers or sensitive fields while retaining enough context to debug.

5. Deduplication (Replay Protection)

Prevent retries or duplicate sends from triggering the same workflows.

• Configure one or more deduplication keys (e.g., X-GitHub-Delivery, event.id) and a window to drop duplicates.
• Helps defend against replays alongside HMAC signatures.

6. One-Time Verification Challenge (CRC)

Some providers (Slack, Zoom, Okta, etc.) send a one-time challenge during webhook registration. Configure:

• Challenge Detection — a rule that identifies the registration request (e.g., header or payload field).
• Response — status code, headers, and body to echo or sign back as required.

Observability (where to look)

When a request hits your listener, you’ll see up to three logs in order:

1. listener.webhook.trigger — raw request received.
2. listener.webhook.processor.update — validated/transformed/published (or rejected/debounced).
3. listener.webhook.plugin.trigger — which plugins were evaluated/triggered/skipped.

Use the Webhook Logs & Troubleshooting guide for “plugin never ran” and similar playbooks.