Bring real events into your development workflow.

API access

Create an API key under Settings. Use a read-only key for inspection and a write-scoped key for changes. Keep API keys on your server. The API reference covers endpoint and event operations.

Forward events to localhost

Build your handler against real provider traffic without a tunnel. shellorbit-listen watches one endpoint and sends a copy of each new event, with its original headers and body, to a URL on your machine. Your destinations still receive every event as usual.

export SHELLORBIT_API_KEY=your_read_only_key
node shellorbit-listen.mjs ep_example http://localhost:3000/webhooks

Download shellorbit-listen. It needs Node 18 or later and has no dependencies. The local development guide covers the options.

Send events through the API

Send your own application’s webhooks through ShellOrbit and they get the same storage, signing, retries, and replay as a received one. Post the body with a read and write key:

POST /v1/endpoints/ep_example/events
Authorization: Bearer YOUR_SERVER_SIDE_API_KEY
Content-Type: application/json

{"type":"invoice.paid","data":{"id":"inv_123"}}

The sending guide covers what the destination receives and the limits.

Processing receipts

HTTP delivery and application processing are separate outcomes. After committing your database transaction or completing a background job, report processed for the ShellOrbit event ID. A receipt is your application’s report; it is not independent proof of a business action.

POST /v1/events/evt_example/processing
Authorization: Bearer YOUR_SERVER_SIDE_API_KEY
Content-Type: application/json

{"state":"processed","reference":"order_123"}

Supported states are processing, processed, and failed. A completed receipt cannot be downgraded by a late failure callback. Do not include secrets or personal data in references and details.

Download the JavaScript processing client.

Regression fixtures

Open Test fixtures in the dashboard. Import an event, remove sensitive values, and explicitly save the edited copy with its own expiry. Choose the expected response status and any required JSON response fields.

Export the fixture and use the Python regression runner against a local or staging endpoint:

python3 run-fixtures.py fixture.json \
  --target http://localhost:8080/webhook \
  --confirm-test-target

Use --repeat 2 to exercise duplicate requests, --reverse for reverse suite order, and --timeout 5 to bound response time. Failed assertions return a nonzero exit code for CI. Requests contain the sanitized JSON and a fixture identifier; they do not reproduce production provider signatures.

Transformation previews

The endpoint workbench supports rename, pick, drop, wrap, and add. Preview against sample JSON before saving. This is a declarative transformation system, not arbitrary code execution.

Delivery identifiers

Use the event identifier for application idempotency. Keep delivery attempts and replay runs separate in your logs: a retry is another attempt to deliver an event, not a new business event.

Download a CI workflow example. Replace the example handler command with your local test receiver. The runner rejects redirects, expired exports, unsafe target credentials, and oversized suites or responses. It never sends a fixture automatically when you export it.