Waybill

Docs

Clear documentation
for real-world use.

Get up and running with setup guides, API references and delivery behaviour from the current project.

View on GitHub
Search topic names and keywords. Press Enter to open the first result.

Start here

Authentication

The public documentation requires no sign-in. Caller authentication and webhook verification are separate concerns in the current project.

Current API access

The Express API has no caller authentication middleware, API-key validation or OAuth flow. Its routes currently require no Authorization header. A tenant UUID filters or associates records; it does not establish ownership or authorize a caller.

Hosted sign-in and an authenticated tenant dashboard are not implemented. The examples here describe local development, not a hosted account or a public production API.

Outbound HMAC signatures

Workers serialize the event envelope once and sign its exact bytes with the tenant’s hmacSecret. The signature uses HMAC-SHA256 and is sent in this header format:

Signature header format
X-Waybill-Signature: sha256=<64 lowercase hexadecimal characters>

Verify the raw request bytes before parsing JSON. Reformatting whitespace, changing key order or signing only the payload changes the signed data. The project’s verifyWebhookSignature helper validates the format and compares digests with a timing-safe comparison.

Verify locally

Configure RECEIVER_TENANT_ID and RECEIVER_HMAC_SECRET to match the tenant record, then run:

Start the verifying receiver
bun run dev:receiver

The included receiver rejects an invalid signature with 401 and a signed envelope for an unexpected tenant with 403. HMAC verification authenticates the signed bytes; the current envelope has no timestamp-based replay protection. Handle duplicate events at the receiver.