Alerts and usage warnings
Hear about a failing destination by email, Slack, or Discord, about your allowance before it runs out, and about your week every Monday.
These pages describe ShellOrbit as it runs today. Breaking changes to the HTTP API are announced before they ship, and existing request and response shapes stay supported.
When is an alert sent?
When one endpoint fails the number of deliveries in a row you choose in Settings, Alerts: 3, 5, 10, 25, or 50. Five is the default. After an alert, the same endpoint stays quiet for an hour, so a destination that is down for a morning sends you one message rather than one per event.
Events keep arriving and being stored while you fix the destination. When it is back, replay what failed.
Who gets the email?
The owners and admins of the account, and every extra address you list on the alerts page. Email alerts are on every plan, including the free one. An alert names the endpoint and the failure count and links to it. It never contains the payload.
How do I send alerts to Slack or Discord?
On Pro and Business, paste an incoming webhook URL on the alerts page:
- Slack: create an incoming webhook for the channel. The URL starts with
https://hooks.slack.com/services/. - Discord: open the channel settings, then Integrations, then Webhooks, and copy the webhook URL. It starts with
https://discord.com/api/webhooks/.
Slack and Discord each get a message in their own format, with a link back to the dashboard. Discord mentions are switched off, so an endpoint name cannot ping a whole server. Any other HTTPS URL, such as Microsoft Teams, Mattermost, or your own handler, gets one JSON body:
{
"text": "ShellOrbit: 5 deliveries in a row have failed for the endpoint \"Stripe production\". ...",
"content": "...the same text...",
"message": "...the same text...",
"url": "https://app.shellorbit.com/endpoints/detail?id=ep_example"
}A webhook URL is a credential: anyone holding it can post into that channel. It is shown once while you add it, then only in masked form. Alert webhooks are held to the same rules as destinations, so a private or internal address is refused, and redirects are not followed.
How do I check that alerts arrive?
Press Send test alert on the alerts page, or call POST /v1/alerts/test. A test message goes to every saved channel, and the result for each one comes back: sent, or the reason it was not, such as the status code a webhook answered with. The test uses your saved settings, so save first.
Will I be warned before I run out of events?
Yes, on every plan. At 90 percent of the events your plan includes for the month, the same people get one warning:
- On the free plan, nothing stops yet. Receipt continues up to twice the included volume, then new events are refused with a 429 until the month ends or you upgrade. See limits.
- On a paid plan, the warning states your overage rate, so you can decide whether to upgrade before any overage exists.
The warning goes out once per month, and it is sent even if failure emails are switched off. On Pro and Business it also goes to your Slack, Discord, or webhook alerts.
What is in the weekly digest?
Every Monday at about 08:00 UTC, the owners and admins, and the extra addresses on the alerts page, get one email about the week just gone, Monday to Sunday:
- Events received, delivered, and failed after every retry, with the delivery rate.
- The busiest day.
- How much of this month’s included events you have used.
- Any endpoint that is paused, or has failed at least as many deliveries in a row as your failure threshold.
A week with no events and nothing that needs attention sends nothing. The digest is on for every plan by default. Switch it off with Send a weekly delivery health digest on the alerts page.
What about the free trial?
If you start a paid plan with the 7 day free trial, the owners and admins get an email about two days before it ends, saying the date and the amount of the first payment. Cancel before then from Plans and billing to stay on the free plan.