Push Delivery
Push subscriptions over KubeMQ — the per-subscription delivery worker, wrapped JSON envelope vs no_wrapper, 2xx-acks, retry with backoff, and dead-letter.
A subscription with a push_config is delivered push-style: instead of the client pulling, a
per-subscription connector worker pulls from the queue gcp.sub.{s} and POSTs each message to
your HTTP(S) endpoint. This guide covers the delivery worker, the envelope shape, the no_wrapper
mode, optional OIDC auth, the HTTPS / localhost rule, and the retry → dead-letter behavior.
Pull ↔ push
A subscription is either pull or push, and you switch between them at any time:
CreateSubscriptionwith apush_config, orModifyPushConfigwith one, starts a per-subscription delivery worker.ModifyPushConfigwith an empty config returns the subscription to pull.- Workers start on
CreateSubscription/ModifyPushConfig(push), stop on switch-to-pull or delete, and drain on connector shutdown.
See Subscribing for the pull paths.
The wrapped envelope
By default the worker POSTs a wrapped JSON envelope:
{
"message": {
"data": "<base64>",
"attributes": { "key": "value" },
"messageId": "...",
"publishTime": "...",
"orderingKey": "..."
},
"subscription": "..."
}datais base64-encoded — decode it on receipt.attributesare the user attributes; the reserved_pubsub_*tags are not surfaced here.messageId/publishTime/orderingKeymirror the message metadata.
no_wrapper mode
When the subscription's push config sets no_wrapper, the worker POSTs the raw message body
instead of the envelope, with the attributes surfaced as x-goog-* headers when configured. Use
this for endpoints that expect the payload directly.
Acknowledgement
The HTTP response status is the ack signal:
| Endpoint response | Effect |
|---|---|
2xx | The message is acked. |
Non-2xx / timeout | Retried with backoff. |
| Retry exhaustion | Republished to the subscription's dead-letter topic if one is set, else dropped (and a metric increments). |
The retry → dead-letter pipeline shares the same dead-letter machinery as the pull paths — see Reliability.
OIDC authentication
When the push config sets an oidc_token, the worker adds an OIDC JWT as
Authorization: Bearer <jwt>. The token audience defaults to the endpoint URL, letting your
endpoint verify the request originated from the connector. Without oidc_token, no Authorization
header is sent.
HTTPS / localhost rule
Push endpoints must be HTTPS. Plain http:// is allowed only for localhost (local
development). Any non-localhost endpoint must be https://. This matches Google's push-endpoint
requirement and keeps message data off the wire in cleartext. It is the connector's outbound
transport rule and is independent of the inbound emulator mode — which is insecure gRPC by design.
See Connectivity & emulator mode.
Node-local caveat (cluster)
Push state is node-local. The per-subscription worker and its in-flight retries live on the node that runs the worker. In a cluster, push subscriptions are part of the node-local family — use a sticky load balancer (session affinity) so a subscription's push worker and its retries stay on one node. Single-node deployments are unaffected. See Reliability.
Error quick reference
| Trigger | Result |
|---|---|
| Non-localhost endpoint over plain HTTP | rejected (HTTPS required) |
Endpoint returns non-2xx / times out | retried with backoff |
| Retries exhausted, DLQ set | republished to the dead-letter topic |
| Retries exhausted, no DLQ | dropped (+ metric) |
Related
Was this page helpful?
Publishing
Create topics and publish over KubeMQ — single and batch Publish, server-assigned ids and publish time, ordering keys, and the publish-once-fan-out model.
Reliability
Delivery guarantees over KubeMQ — dead-letter topics, retry backoff, at-least-once redelivery, node-local exactly-once, and retention clamped to the broker.