Concepts
Webhooks
The word "webhook" gets used three ways in Mobius. The direction is the only thing that matters; everything else follows.
| Surface | Direction | Purpose |
|---|---|---|
| Project webhooks (this page) | Outbound | Mobius POSTs run events to your URL. |
| Webhook triggers | Inbound | External systems POST to start a run. See Triggers. |
| Provider receivers | Inbound | Stripe, Clerk, Slack, etc. notify Mobius itself. Not managed by you. |
This page covers the outbound subscription, which is the one you'll configure most often.
What you'd use one for
Forwarding run.completed and run.failed into your existing pager,
posting run summaries to your internal Slack, kicking off a downstream
job, writing run history to a data warehouse. Pretty much any
"something else needs to know when a run finishes" use case.
If you only need to operate Mobius (start runs, watch progress, cancel),
you probably don't need outbound webhooks at all. Use
mobius automations stream-automation-run-events instead.
Choosing what to subscribe to
Wildcards are first-class. Three useful patterns:
- One narrow event (
run.failed). For pager integrations: noisy events stay out of the pager. - One subtree (
run.*). For a data warehouse that wants the full run lifecycle. - Everything (empty
eventslist). For a debug sink you can grep.
You usually want narrow subscriptions per receiver. One pager hook with
run.failed, one warehouse hook with run.*. Don't subscribe to
events you'll just throw away.
Creating one
mobius webhooks create \
--name "Run status sink" \
--url "https://hooks.example.test/mobius/run-status" \
--events '["run.completed","run.failed"]'The response includes a one-shot signing secret. Store it; you'll use it to verify deliveries. Rotate with:
mobius webhooks rotate-secret whk_01...Test reachability before you trust it in production:
mobius webhooks ping whk_01...Verifying deliveries
Every delivery is HMAC-signed. You don't need to implement verification
by hand: the SDKs ship a verifyWebhook (or equivalent) helper that
handles the signature, timestamp drift, and replay deduplication. Pass
your raw request body and the secret you got at creation.
Three things to do at the receiver:
- Verify the signature.
- Reject deliveries with stale timestamps (more than five minutes of drift).
- Deduplicate by
delivery_id. Retries reuse the same id.
Retry policy and inspection
Failed deliveries (network errors, 5xx, 408, 429) retry up to 10 times on a five-second processing cycle. Other 4xx responses are treated as permanent failures and aren't retried. Each attempt has a 10-second HTTP timeout.
To see what's been attempted:
mobius webhooks list-deliveries whk_01... --limit 20If you're chasing a missing event, that's the first place to look.
Common CLI operations
mobius webhooks list
mobius webhooks get whk_01...
mobius webhooks update whk_01... --file webhook.json
mobius webhooks delete whk_01...
mobius webhooks rotate-secret whk_01...
mobius webhooks ping whk_01...
mobius webhooks list-deliveries whk_01...Related
- Triggers for the inbound side.
- Runs for the events you'll most often subscribe to.
- API overview for verification specifics if you're not using the SDK.