Queuey docs

Reference

Headers & status codes

The headers Queuey reads on ingress and sends on delivery, and the HTTP status codes you can get back when you POST an event.

Headers Queuey reads (ingress)

HeaderMeaning
Content-Typeapplication/json for JSON event bodies.
X-Api-KeyAPI-key authentication. Format: qak_<keyId>.<secret> (when the queue's ingress auth is API key).
Idempotency-KeyProducer-asserted idempotency key. A duplicate within the dedup window short-circuits to the already-accepted event.
X-Queuey-Key-IdSigned-request: the HMAC signing key id.
X-Queuey-TimestampSigned-request: Unix seconds, checked for skew (replay protection).
X-Queuey-NonceSigned-request: a unique value, single-use (replay protection).
X-Queuey-Content-SHA256Signed-request: lowercase hex SHA-256 of the raw body.
X-Queuey-SignatureSigned-request: lowercase hex HMAC-SHA256 of the canonical string.
X-Queuey-PathLoop-prevention chain. Refused past the configured hop budget or on a cycle.

Headers Queuey sends (delivery)

HeaderMeaning
AuthorizationBearer / Basic — set per the target's auth mode (incl. OAuth2).
Idempotency-KeyThreaded from the event so an idempotent receiver can dedupe across retries.
X-Queuey-Event-IdThe event's public id, for traceability at the receiver.
X-Queuey-PathQueuey appends its segment, so a downstream Queuey can detect loops.
X-Queuey-Signature (+ Key-Id / Timestamp / Nonce)Present when the queue signs outbound deliveries (HMAC).
Your GroupKey headerOpt-in: the event's GroupKey under a name you choose (see Customer context).
Your mapped headersOpt-in: values lifted off the inbound request at accept — a header, a query parameter, or a top-level body field — sent under names you choose. Snapshotted per event, identical on every retry. See Customer context → Forward more than the GroupKey.
Your static headersFixed name/value pairs configured on the target. Always win a name collision.

Precedence on a name collision, lowest to highest: mapped headers, Queuey's own headers, then static headers / auth / signing. The console refuses a collision at save; the order is the backstop.

Signing does not cover mapped or GroupKey headers. The HMAC canonical string is built from method, path, query, body and the signature headers themselves — a forwarded header travels unsigned. Treat it as context, not as a verified claim.

Names that can never be forwarded

HeaderWhy
X-Queuey-*Queuey's own vocabulary — the whole prefix, including the HMAC headers.
Idempotency-Key, X-Idempotency-Key, X-Delivery-KeyDedup identity; forwarding one would let a producer forge it.
Authorization, Proxy-Authorization, Cookie, Set-Cookie, X-Api-KeyCredentials. Forwarding one hands the producer's secret to every receiver of the queue.
Host, Content-Type, Content-Length, Connection, Transfer-Encoding, Expect, Upgrade, TETransport — the outbound request owns these.

Ingress status codes

Errors return a consistent envelope so clients can branch on the code: { "error": { "code": "queue_paused", "message": "…" } }.

StatusMeaning
202 AcceptedThe event was accepted and persisted. The body returns the eventId; delivery is asynchronous. A duplicate Idempotency-Key returns 202 with replayed:true.
400 Bad RequestValidation error — code is queue_paused, invalid_context_key, or sandbox_query_not_allowed.
401 UnauthorizedMissing or invalid credentials — missing_api_key, invalid_api_key, invalid_signature, timestamp_out_of_range, replayed_request.
403 ForbiddenValid but denied — ip_not_allowed, client_scope_denied, missing_permission.
404 Not FoundUnknown workspace or queue — not_found.
409 ConflictThe queue is paused — queue_paused.
422 Unprocessable EntityThe X-Queuey-Path chain exceeded the hop budget or formed a cycle — loop_detected / max_hops_exceeded.

Related