Start here
Getting started with Waybill
Waybill accepts events over HTTP, stores them with a transactional outbox, and delivers signed webhooks through SQS workers. These docs describe the current Bun project and its local API.
Send your first event
With the API running, replace the tenant placeholder with an existing tenant UUID. No SDK or authentication header is required by the current ingestion route.
TerminalPOST /events
curl --fail-with-body --max-time 10 \
--request POST http://127.0.0.1:3000/events \
--header 'Content-Type: application/json' \
--data '{
"tenantId": "REPLACE_WITH_TENANT_UUID",
"type": "order.shipped",
"payload": { "orderId": "order_123" }
}'send-event.ts · BunPOST /events
const response = await fetch("http://127.0.0.1:3000/events", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
tenantId: "REPLACE_WITH_TENANT_UUID",
type: "order.shipped",
payload: { orderId: "order_123" },
}),
signal: AbortSignal.timeout(10_000),
});
if (!response.ok) {
throw new Error(`Event rejected: ${response.status}`);
}
console.log(await response.json());send_event.py · Python 3POST /events
import json
import urllib.request
body = json.dumps({
"tenantId": "REPLACE_WITH_TENANT_UUID",
"type": "order.shipped",
"payload": {"orderId": "order_123"},
}).encode("utf-8")
request = urllib.request.Request(
"http://127.0.0.1:3000/events",
data=body,
headers={"Content-Type": "application/json"},
method="POST",
)
with urllib.request.urlopen(request, timeout=10) as response:
print(json.load(response))201 Created confirms persistence, before delivery.
REPLACE_WITH_TENANT_UUID with an existing tenant ID. Webhooks go to the worker’s configured RECEIVER_URL. Swipe or scroll within the code to read long lines.Before you send
Start with the local setup to configure PostgreSQL, Redis, AWS and a verifying receiver. The worker sends every event to its configured RECEIVER_URL.
A 201 response confirms that the event and outbox entry were saved. Publication and delivery happen asynchronously. Receivers must handle duplicate event IDs.
Follow the event
- Events: request fields, validation and persistence.
- Architecture: outbox, poller, SQS and workers.
- Retries and dead letters: failure handling and manual replay.