Ingest endpoints
What an endpoint is, what it accepts, and how to organise endpoints across providers and environments.
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.
What is an endpoint?
An endpoint is one ingest URL plus the configuration attached to it: destinations, retry policy, transformation rules, alerts, and retention inherited from your plan. One endpoint usually maps to one provider in one environment, for example Stripe in production.
What does an endpoint accept?
- Any HTTP method that carries a body, with POST being the normal case.
- Any content type. The body is stored as bytes, not parsed, so JSON, form encoding, XML, and binary all work.
- Bodies up to 350 KB inline. Larger bodies up to 5 MB are stored in object storage and delivered the same way. Anything larger is refused at the edge rather than half accepted.
- Any headers the provider sends, stored verbatim including signature headers.
What does it return?
| Status | Meaning |
|---|---|
| 202 | Stored and queued for delivery |
| 400 | Malformed request, for example a body that exceeds the maximum size |
| 404 | No endpoint with that id, or the endpoint was deleted |
| 429 | Rate limited at the edge, retry later. Providers with their own retry logic will resend |
| 5xx | Our fault. Providers should retry, and most do |
How should I organise endpoints?
One endpoint per provider per environment. That keeps retry policy, alerting, and the event log readable, and it means revoking a leaked URL affects one provider rather than everything.
Endpoint ids are unguessable, so a separate endpoint per environment is also the cleanest way to keep staging traffic out of production data.
How do I rotate an endpoint?
Create a new endpoint, update the provider, confirm traffic has moved by watching both event logs, then delete the old one. Deleting an endpoint stops new receipts immediately. Events already stored stay readable and replayable for the rest of your retention window.
Can I pause an endpoint?
Yes. Pausing keeps receiving and storing events while holding delivery. Resume and the queue drains in order. This is the safe way to handle a planned migration or a destination that is down for maintenance.