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

Events

POST /events is the ingestion endpoint on the Express API. Its local default origin is http://127.0.0.1:3000.

Request body

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" }
  }'
201 Created confirms persistence, before delivery.
Replace 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.

FieldRequirement
tenantIdExisting tenant UUID.
typeNonempty string, at most 200 characters.
payloadRequired JSON value; null is accepted.

There is no destination field or ingestion idempotency key in this contract. Repeating an ingestion request can create another event.

Response and errors

On success, 201 returns eventId, outboxId and storedIn (postgres or s3). It confirms persistence, before queue publication or delivery.

StatusMeaning
201Event and outbox transaction committed.
400Schema validation failed; Express also rejects malformed JSON.
404Tenant does not exist.
429Ingestion token bucket exhausted; Retry-After reports seconds.
500Internal failure.
413Request exceeds Express’s 2 MB JSON-body limit.

Large payloads

Payload JSON above SQS_MAX_MESSAGE_BYTES (default 262144 bytes) is uploaded to S3 before the database transaction. The event and queue message retain a pointer instead of the oversized inline payload. This is a project threshold, not a claim about the current SQS service maximum.

The event and outbox entry commit atomically in PostgreSQL. S3 upload and the database transaction are separate operations.