Govern
Webhooks
A project webhook is an outbound subscription that sends Mobius events to your HTTPS endpoint.
This direction distinguishes it from two other webhook surfaces:
| Surface | Direction | Purpose |
|---|---|---|
| Project webhook | Outbound | Mobius sends project events to your system. |
| Webhook trigger | Inbound | Your system sends a request that starts a run. |
| Provider receiver | Inbound | A connected provider notifies Mobius. |
Use a project webhook when another system must react to Mobius state changes. Use a trigger when an external system should start a Mobius run.
Choose events narrowly
A webhook can subscribe to one event, an event family, or every project event. Most receivers should be narrow:
- Subscribe a pager to
run.failed. - Subscribe a run-history sink to
run.*. - Subscribe a temporary diagnostic receiver to everything.
Separate receivers by purpose. A pager should not receive routine lifecycle events merely to discard them.
Create a webhook in the app
- Open Settings > Webhooks.
- Click New webhook.
- Enter a name and the external HTTPS URL.
- Add exact event names or wildcard families.
- Create the webhook.
- Save the one-time signing secret immediately.
Open the webhook and click Ping before relying on it. A successful ping confirms that Mobius can reach the receiver; it does not replace signature verification in your application.
Inspect delivery health
The webhook detail page shows recent deliveries and attempts. Start there when the destination appears to miss an event.
Mobius retries network failures, timeouts, rate limits, and server errors. Other client errors are permanent because sending the same invalid request again would not help.
Every delivery has a stable identity. Receivers should deduplicate retries so a temporary failure cannot cause the same side effect twice.
Protect the receiver
Verify every delivery with the SDK helper before trusting its body. The helper checks the signature, timestamp, and replay identity using the secret shown at creation.
Rotate the signing secret from the webhook detail page when it may have been exposed. Rotation shows the replacement once, so coordinate the receiver update before losing access to it.
Next
- Implement verification with the Webhooks API.
- Operate subscriptions from the CLI command reference.
- Start runs from inbound calls with triggers.
- Choose event names from the event catalog.