Relay#
POST /relayThe single ingest entrypoint. Authenticated with a relay token.
Headers#
| Header | Required | Description |
|---|---|---|
X-Junction-Token |
Yes | relay-type token. |
X-Junction-Event |
Yes | Event type identifier. Must match /^[a-zA-Z0-9._-]+$/ — alphanumerics, dots, underscores, hyphens. |
X-Junction-Trace-ID |
No | Caller-supplied UUIDv4. Generated if absent. |
Request#
The body must be a JSON object with the caller’s data nested under a payload key:
POST /relay
Content-Type: application/json
X-Junction-Token: <relay token>
X-Junction-Event: order.placed
{ "payload": { "order_id": 4821, "total": 59.99 } }| Field | Rules |
|---|---|
payload |
required, object |
payload is opaque to Junction — never inspected for routing, forwarded to destinations exactly as received. It’s what ends up under payload in the queue envelope
and in the stored event log
.
Response#
202 Accepted
X-Junction-Trace-ID: <UUIDv4>No response body. Delivery is asynchronous — a 202 confirms the event was accepted and routed, not that any destination received it. Use the trace ID with the event logs
endpoints to track delivery outcome.
Error responses#
| Status | Cause |
|---|---|
| 400 | X-Junction-Event header missing or fails the format regex, or the request body is not valid JSON |
| 401 | X-Junction-Token missing, invalid, or not a relay-type token |
| 415 | Content-Type is not application/json |
| 422 | payload field missing or not an object |
See Errors for the response body shape.