Mobius

Sign inGet started
GuidesAPI Reference
Sign inGet started

Guides

A webhook trigger gives any HTTP client the ability to start workflow runs — for a CI pipeline, a monitoring alert, or any service that sends events to a URL. An inbound POST to the trigger's receive URL fires it and creates a run for every matching target.

Before you start

  • You have a Mobius API key exported as MOBIUS_API_KEY. See API keys if you do not.
  • Your project handle is exported as PROJECT and your API base URL as MOBIUS_BASE_URL.
  • A workflow definition exists in the project and its ID is exported as WORKFLOW_ID.

Walkthrough

  1. Create the webhook trigger with POST /v1/projects/{project}/triggers. The response returns the trigger id and a receive_url — the inbound endpoint your external system posts to. Capture both as $TRIGGER_ID and $RECEIVE_URL.

    curl -X POST "$MOBIUS_BASE_URL/v1/projects/$PROJECT/triggers" \
  -H "Authorization: Bearer $MOBIUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci-build-complete","kind":"webhook","targets":[{"workflow_id":"'"$WORKFLOW_ID"'"}]}'

  2. Fire the trigger by posting any JSON payload to $RECEIVE_URL. Mobius evaluates each target's condition against the payload and starts a run for every target that matches.

    curl -X POST "$RECEIVE_URL" \
  -H "Content-Type: application/json" \
  -d '{"ref":"main","sha":"abc123"}'

  3. Confirm the fire with GET /v1/projects/{project}/triggers/{id}/fires. The first entry in items has status: success and a run_id pointing to the created run.

    curl "$MOBIUS_BASE_URL/v1/projects/$PROJECT/triggers/$TRIGGER_ID/fires" \
  -H "Authorization: Bearer $MOBIUS_API_KEY"

Follow-ups

  • Secure the inbound endpoint: add "webhook_secret": "<your-secret>" to the createTrigger request body. Mobius then validates the X-Mobius-Signature header on each inbound POST.
  • Map payload fields to run inputs: add an input_mapping object to the target — e.g. {"commit_sha": "$.sha"} — to extract fields from the inbound payload and pass them as workflow inputs.
  • Fire on a schedule: set "kind": "schedule" and include "source_config": {"cron": "0 9 * * 1-5"} instead of "kind": "webhook".
  • Pause without deleting: set "enabled": false via PATCH /v1/projects/{project}/triggers/{id}.
  • Get notified when runs complete: subscribe to outgoing run events with POST /v1/projects/{project}/webhooks. Mobius posts run.completed, run.failed, and other run events to your endpoint; failed deliveries are retried up to 10 times and each POST carries X-Mobius-Signature: sha256=<hex>.

Troubleshooting

  • Fire status: skipped: the concurrency_policy is forbid and a run from this trigger is still active, or a target condition evaluated to false. Check the targets[].condition expressions or switch to "concurrency_policy": "allow" to start runs unconditionally.
  • Fire status: failed: the error field on the fire record contains detail. A common cause is a target workflow_id that no longer exists in the project.
  • 401 on management API calls: the API key is missing or revoked. Re-issue it at API keys and re-export MOBIUS_API_KEY.

See also