Reference
Webhooks
A webhook is Mobius calling one of your systems the moment something happens. A job failed, so your on-call tool pages someone. A job finished, so your PSA gets a note on the ticket.
You give Mobius a URL and a list of events. Mobius sends a signed message to that URL each time one of those events occurs.
Which direction?
Three things get called webhooks and they point different ways. Getting them confused wastes an afternoon, so:
| Direction | What it does | |
|---|---|---|
| Project webhook (this page) | Mobius → you | Tells your system something happened in Mobius |
| HTTP trigger | You → Mobius | Your system asks Mobius to start a job |
| Provider receiver | Provider → Mobius | Slack or GitHub tells Mobius something happened |
If you want a job to start, you want a trigger. If you want to know a job happened, you want a webhook.
Subscribe narrowly
A webhook can listen for one event, a family of them, or everything. Nearly always, narrow is right:
- Your paging tool subscribes to
run.failedand nothing else. - Your reporting sink subscribes to
run.*. - A temporary debugging receiver subscribes to everything, for an hour.
Give each receiver its own webhook. A paging tool that has to receive and discard routine events is one bad filter away from waking somebody up at 3am for nothing.
Setting one up
- Open Settings > Webhooks.
- Click New webhook.
- Enter a name and your HTTPS URL.
- Add the event names you want, exactly or with a wildcard.
- Create it.
- Save the signing secret right then. It's shown once.
Then open the webhook and click Ping before you rely on it. A successful ping proves Mobius can reach your endpoint. It doesn't check that your endpoint verifies signatures, which you still have to do.
When something doesn't arrive
The webhook detail page shows recent deliveries and every attempt. Start there.
Mobius retries network failures, timeouts, rate limits, and server errors. It doesn't retry other client errors, because sending the same invalid request again won't help.
Every delivery has a stable identity. Your receiver should discard duplicates, because a retry after a timeout can deliver something you already handled. Otherwise one slow response turns into two tickets.
Protecting the receiver
Verify every delivery before trusting it. The SDK helper checks the signature, the timestamp, and the replay identity using the secret from setup.
This matters more than it sounds. Your webhook URL is reachable by anyone who learns it, and without verification anyone could send you a convincing "job failed" message.
Rotate the secret from the webhook's detail page if it might have leaked. The replacement is shown once, so have the receiver update ready before you rotate.
Next
- Verify deliveries with the Webhooks API.
- Manage subscriptions from the CLI command reference.
- Start jobs from inbound calls with triggers.
- Find event names in the event catalog.