How-to guide

Payloads: what your receiver gets

Your receiver gets the payload as it was published, as normalized JSON, or as a CloudEvents v1 event — you choose per workspace or queue. A JSON Patch mutation changes it on the way out when you set one, and three privacy levers decide how long Queuey keeps it and who can look at it.

What the receiver gets

With the default format, Raw (as received), and no payload mutations, the request body is the bytes Queuey accepted, unchanged — on the first attempt, on every retry and on a replay. Nothing is added to it: no envelope, no metadata fields. The Content-Type is the media type the event was published with, without parameters such as charset, or application/octet-stream when it had none.

what the receiver gets
POST /orders HTTP/1.1
Host: api.example.com
Content-Type: application/json
Idempotency-Key: order-10042-paid
X-Queuey-Event-Id: evt_…

{ "orderId": "10042", "status": "paid" }

The event's identity travels in headers: by default Idempotency-Key — the same on every attempt — and X-Queuey-Event-Id. The headers reference lists the headers a delivery carries, including those your delivery authentication and request signing add.

Payload format

Set it under Delivery → Delivery behavior → Payload & ordering → Payload format, on a workspace or on one queue. The format is applied after any JSON Patch and before signing, so an HMAC signature covers the bytes the receiver gets — verify it over the body you received.

FormatWhat the receiver gets
Raw (as received)The body as it was published, after any JSON Patch. The default, and the only format for forwarding a provider's signature and for Stripe signature recalculation.
Normalized JSONA body published as JSON, parsed and written back compact: whitespace gone, every value unchanged. A body not published as JSON, or one that doesn't parse, goes as it is.
CloudEvents v1The event wrapped as a CloudEvents v1 event in structured mode, sent as application/cloudevents+json.
Formats chosen before they applied
Until the payload format applied at delivery, every receiver got the body as published, whatever was selected. When it started to apply, queues and workspaces that had normalized JSON or CloudEvents v1 stored were set back to Raw (as received), so no receiver's body changed without a choice. Pick the format again if you want it.

CloudEvents v1

For receivers that speak the CloudEvents spec, the event goes out in structured mode: the payload becomes data, with the event's context alongside. Every value comes from the stored event, so a retry and a replay send the same bytes.

a CloudEvents delivery
POST /hooks/orders HTTP/1.1
Content-Type: application/cloudevents+json; charset=utf-8

{
  "specversion": "1.0",
  "id": "evt_nd9qgy1sjPIW",
  "source": "/queues/que_Rp2yPELnp4sr",
  "type": "order.shipped",
  "time": "2026-09-30T08:15:00.0000000Z",
  "subject": "acme",
  "datacontenttype": "application/json",
  "data": { "orderId": "10042", "status": "shipped" }
}
AttributeValue
idThe event's id — the same value as the X-Queuey-Event-Id header.
source/queues/ and the queue that delivers the event. For a Queuey Connect copy it is the producer's stream, the same for every integrator.
typeThe event type (X-Queuey-Event-Type, or wherever the queue reads it from). ai.queuey.event when the event has none.
timeX-Queuey-Occurred-At when the producer sent it; otherwise when Queuey received the event. A Queuey Connect copy keeps the producer's time.
subjectThe event's customer key (GroupKey), when it has one.
datacontenttypeThe media type the event was published with.
dataJSON content as JSON and text as a string; anything else, or bytes that aren't valid UTF-8, as data_base64.

Change the body on the way out

Payload mutations apply JSON Patch (RFC 6902) operations to the outbound body — add a field, strip an internal one — without touching the producer. Set them under Delivery → Delivery behavior → Payload mutations, on a queue, or on the workspace to apply them to every queue in it:

JSON Patch mutation
[
  { "op": "add",    "path": "/source", "value": "queuey" },
  { "op": "remove", "path": "/internalNote" }
]
  • Queuey applies the add, remove and replace operations. A patch that contains any other operation — move, copy, test — is skipped.
  • Patches run in order at delivery time, on the stored body — so a patch you add or change also applies to retries and replays of events already in the queue.
  • A patch that cannot be applied to an event — a replace of a field the event does not have, say — is skipped as a whole, and the event is delivered without it. Removing a field that is not there is not an error.
  • A patched body is sent as compact JSON with the event's Content-Type. A body that is not JSON is delivered unchanged. The payload format applies after the patch, so under CloudEvents v1 the patched body is the event's data.
Raw and no mutations keep signatures valid
For provider webhooks your receiver already verifies (a signature over the raw body), keep the queue on Raw (as received) and without payload mutations — its own and the workspace's — so the bytes stay exactly as the provider signed them. Queuey doesn't forward the signature header by default. The Stripe guide is the worked example, including forwarding that header as a mapped header.

Payload privacy

Three levers on a workspace or queue (Delivery → Delivery behavior → Payload privacy) decide how much of a payload exists and who can look at it. Payload in the console: shape (default — the event list and detail show the payload's structure, never its values; an operator clicks Reveal, and that look is written to the payload access log), values, or shapeOnly (values are never shown in the console — Reveal is refused for everyone and AI analysis is capped at Shape; delivery and the API are unaffected). Payload after delivery: untilRetention (default — replay possible) or deleteOnSuccess (the payload is deleted the moment the event is delivered; status, attempts and a values-free shape stay, delivered events can no longer be replayed). Receiver responses: onFailure (default), always or never — when the receiver's response body and headers are kept per attempt. You can also cap body size with maxBytes.

Related