Sources
What a source is, the URL and secret it gives you, how its events are checked and kept, and the limits by plan.
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.
A source is one system that sends its events to ShellOrbit: a GitHub organization, an AWS account, an Okta or Auth0 tenant, your own app, or anything else that signs its webhooks. ShellOrbit checks each event, keeps it for your plan’s history window, and runs the source’s rules over it. A source only receives; it never acts in the system it watches.
Kinds
| Kind | Rules | Signature | Guide |
|---|---|---|---|
| GitHub | Ready-made GitHub rules | GitHub (X-Hub-Signature-256) | Connect GitHub |
| AWS | Ready-made AWS rules | The source URL, plus a header you set on the EventBridge connection | Connect AWS |
| Okta | Ready-made sign in rules | The authorization header Okta sends | Connect Okta |
| Auth0 | Ready-made sign in rules | The authorization token Auth0 sends | Connect Auth0 |
| Your app | Ready-made sign in rules | ShellOrbit (ShellOrbit-Signature) | Send your app’s events |
| Custom | Your own rules | Stripe, Shopify, Paddle, GitHub, Standard Webhooks, or ShellOrbit | Custom sources |
The URL and the secret
Creating a source in Settings, Integrations gives you:
- A URL, such as
https://hooks.shellorbit.com/e/ik_7f3a91c2d4. Anyone with it can post to the source, so keep it out of public code and screenshots. - A secret, shown once. The vendor uses it to sign each request, or sends it in a header, and ShellOrbit checks it on the original bytes before any rule reads the event. Rotate it from the source’s page; update the vendor straight after.
A request whose signature does not check out is kept and marked, never run through the rules, so a forged event cannot raise or hide a finding, and you can still see that someone tried.
Events
Open a source to see what it received: when, the headers, the body, and whether the signature checked out. Mark JSON paths or header names to mask, and they are hidden in the inspector, the API, and anything an AI agent reads.
- An event is acknowledged with
202once it is stored. - Events are kept for your plan’s history window: 15 days on Hobby, 30 on Starter, 60 on Pro, 180 on Business.
- Bodies up to 5 MB are accepted.
Limits by plan
| Hobby | Starter | Pro | Business | |
|---|---|---|---|---|
| Sources | 1 | 5 | 30 | Unlimited |
| Source events a month, fair use, never charged | 15,000 | 75,000 | 150,000 | 750,000 |
| Custom rules | None | 10 | 50 | Unlimited |
| Silent source alerts | No | Yes | Yes | Yes |
| Source IP allowlist | No | No | No | Yes |
Source events are never charged. Past ten times the included volume on a paid plan, or twice on Hobby, new events get 429 until the month turns and are not checked against your rules. Some systems retry a 429 later; GitHub does not redeliver on its own. See limits.
Before production
- Connect a test organization, account, or tenant first.
- Press Send a test event on the source, and check the finding and your alerts.
- Check a real event’s signature result in the source’s events.
- Set silent hours on the sources that should never go quiet.