Skip to main content
A subscription tells Streaming Hub which events go to which destination for your tenant. You manage subscriptions through the /v1 control-plane API, authenticated with an Access Manager token. This page covers the model and the onboarding flows. The API reference has the exact request and response shapes (start from the reference introduction).

​
The subscription model

A subscription records:
  • name: a human label (required, non-blank). A subscription that is not deleted and already holds the name makes the create return 409 subscription_name_taken.
  • sink_kind: one of webhook, pull, sqs, rabbitmq, eventbridge.
  • endpoint: where deliveries go, in a shape that depends on the sink kind (see below).
  • event_types: the keys to deliver. Take each key from the eventKey field of GET /v1/catalog, exactly as served. The hub accepts any well-formed key, so a catalog gap never stalls onboarding. A key that no producer emits matches nothing. Omit the field to receive every event type.
  • origin: an optional exact ce-source pin. Omit it to accept the same key from any producing application.
  • schema_major: the payload major version the subscription follows. Omit it to follow major version 1.
  • timeout_ms: for a webhook only, the per-attempt delivery timeout, from 1000 to 20000 milliseconds. The default is 10000.
  • plan_tier: the delivery tier the subscription runs under.
The endpoint format follows the sink kind:
Queue delivery does not preserve the canonical source-qualified ce-type. SQS and RabbitMQ set ce-type to the bare <resource>.<event> key. EventBridge uses that bare key for DetailType and Detail.type, and its source identifies the hub rather than the producer. Pin origin and keep the subscription identity alongside the delivery when producer identity matters.

​
Two orthogonal status fields

Every subscription carries two independent status fields. Confusing them is the most common source of “why did delivery stop” questions, so keep them separate:
  • verification_state is proof that the destination can actually receive events. It moves through pending_verification → active → degraded, driven by probes. Only an active subscription is deliverable.
  • enabled is the deliverability switch. It is what auto-disable flips off, and what a re-enable turns back on.
Subscription matching requires both: a subscription delivers only when enabled and verification_state = active. Auto-disable lives entirely in enabled and never changes verification_state, so an auto-disabled subscription reads as enabled = false, verification_state = active. See auto-disabling a broken destination for how the two interact.

​
Creating a webhook subscription

A webhook subscription is the simplest to onboard. It needs no credential, only one probe:
  1. Create: POST /v1/subscriptions with sink_kind: "webhook" and your https:// endpoint. Send a unique X-Idempotency header: the hub rejects a create that omits it, before any write. The hub validates the destination URL against private, loopback, and cloud-metadata address ranges before any write. The response returns the new subscription in pending_verification, and the signing secret.
  2. Save the signing secret: no read route returns it. A retry with the same X-Idempotency key returns the same response. The hub stores the secret only as ciphertext. If you lose it, you can only rotate to a new one.
  3. Activate the destination: POST /v1/subscriptions/:id/ping sends a synthetic, signed probe through the real delivery path and reports the classified outcome. A successful probe moves the subscription to active, and that is what makes it deliverable. Deploy your endpoint before you ping: it must answer 2xx.
After the probe succeeds, matching admits the webhook subscription and it starts to receive events. For the full walkthrough from create to a first confirmed delivery, see the quick start. See Consuming events for how to verify the signature on each delivery.

​
Onboarding a queue subscription

Queue subscriptions (sqs, rabbitmq, eventbridge) are born pending_verification and deliver nothing until a probe verifies their destination. How you verify depends on the kind:
  • RabbitMQ: supply a broker credential, verified on write (below).
  • SQS and EventBridge: either supply an outbound credential, verified on write (below), or wire an AWS delegated grant (next section) without storing a credential.
For any queue kind, the outbound-credential flow is three steps:
  1. Create: POST /v1/subscriptions with the queue sink_kind and its endpoint, and no inline credential (the hub rejects an inline sink_config or credential). Send a unique X-Idempotency header, as for any create. The hub stores the subscription pending_verification. Matching excludes it, so it produces no delivery jobs yet.
  2. Supply the credential: PUT /v1/subscriptions/:id/credential with the write-only outbound credential. The hub holds it in memory, probes it immediately (connect and authenticate against the destination), and persists it as ciphertext only if the probe succeeds. A failed probe stores nothing. The hub validates destination addresses against blocked ranges before storage. A successful probe moves the subscription to active.
  3. Active: once active, matching admits the subscription and it begins receiving events.
The credential is write-only: you supply it here and no read path ever returns it, not even masked. To change it, PUT a new one. The same probe-on-write applies.

​
Wiring an AWS delegated grant

For the credentialless AWS path (sqs, eventbridge), the hub delivers by assuming a role in your AWS account. You wire that trust instead of supplying an outbound credential:
  1. Fetch the setup artifacts: GET /v1/subscriptions/:id/setup-artifacts returns a cross-account IAM trust policy, a CloudFormation quick-create link, and a non-secret ExternalId the hub mints for this subscription.
  2. Apply them in your AWS account: create the delivery role from the trust policy (the quick-create link scaffolds it). The role trusts the hub’s principal only under the minted ExternalId condition. That condition closes the confused-deputy gap. A trust policy that omits it fails verification, and never counts as verified.
  3. Register the grant: PUT /v1/subscriptions/:id/delegated-grant with the delivery role ARN, region, and destination. This records non-secret coordinates only. It runs no probe and does not change verification_state.
  4. Verify: POST /v1/subscriptions/:id/verify runs the hardened role-assumption probe and, on success, flips the subscription to active.
No AWS credential crosses these requests. The hub reaches your account by assuming your role under the ExternalId.

​
Rotating a signing secret

POST /v1/subscriptions/:id/secret/rotate mints a new webhook signing secret, returns it, and starts a 24-hour dual-sign overlap. During the overlap the hub signs each delivery with both the new and the previous secret and sends two signature headers. Your consumer can therefore switch to the new secret at any point in the window without dropping deliveries. Rotate cleanly like this:
  1. Call rotate and save the new secret from the response (alongside the overlapUntil timestamp).
  2. Deploy the new secret to your consumer within the overlap window. While your verifier holds both secrets, it accepts a delivery if either signature validates.
  3. After the overlap, retire the old secret.
Only a webhook subscription has a signing secret. The hub rejects rotation for every other sink kind. See handling two signatures during rotation for the consumer-side verification.

​
Recovering an auto-disabled subscription

When a destination stays broken long enough, the hub auto-disables the subscription by flipping enabled = false. To recover it:
  1. Fix the destination (the endpoint, the queue, or the grant).
  2. Call POST /v1/subscriptions/:id/verify. It re-probes the destination. On a successful probe, it re-enables the subscription and clears the auto-disable mark, in place and with the same id and signing secret.
A failed re-probe does not re-enable the subscription, and it moves an active verification state to degraded. Call GET /v1/subscriptions/:id/health for the delivery-health rollup (recent outcomes, dead-letter counts, and the auto-disable verdict). Use it to confirm the destination is healthy before and after.

​
Changing the schema pin and the timeout

PATCH /v1/subscriptions/:id changes two fields. Every body must carry schema_major:
  • {"schema_major": 2} pins the subscription to that major version.
  • {"schema_major": null} clears the pin, so the subscription follows major version 1.
  • On a webhook, add "timeout_ms" to change the per-attempt timeout, or send 0 to return to the 10000 default. Send the current schema_major with it to keep the pin.
The hub rejects any other field, a body without schema_major, or a schema_major below 1. It never silently ignores them, so you can never believe a forbidden change took effect. The event_types and origin fields are immutable. Create a new subscription when either filter must change. A PATCH never changes the endpoint, the sink kind, or the secret. It does not reset verification_state and echoes no secret.

​
Idempotency

The mutating routes (create, delete, PATCH, secret rotate, and delegated-grant registration) require an idempotency key:
The hub rejects a mutation sent without it before any write, with 400 missing_idempotency_key. The store is fail-closed: if the idempotency store is unreachable, the request fails rather than risking a double write. That guarantees a replayed create or rotate returns the original secret instead of minting a new one.
  • Replaying a committed key within its retention window (24 hours by default) returns the original response byte-for-byte, with X-Idempotency-Replayed: true.
  • Reusing a key while its first request still runs, or with a different request body, returns 409 idempotency_conflict. Mint a new key for a corrected request.
The verification routes (ping, verify, PUT /credential, GET /setup-artifacts) are naturally idempotent and require no key. See the platform-wide guidance on retries and idempotency.

​
Next steps

Consuming events

Verify webhook signatures, deduplicate deliveries, and pull events.

How Streaming Hub works

Matching, dispatch, retries, and auto-disable in detail.