Saltar al contenido principal
POST
Create a subscription

Autorizaciones

Authorization
string
header
requerido

A bearer JWT issued by Access Manager. The /v1 surface never reads a tenant from the body, path, or query. Machine callers obtain a token with the Access Manager client-credentials flow. The /admin surface authorizes against an operator scope and carries no tenant context.

Encabezados

X-Idempotency
string
requerido

A client-chosen unique key that makes this mutation at-most-once. A mutation sent without it is rejected before any write with 400 missing_idempotency_key. Reusing the same key with an identical request replays the original response byte-for-byte (with X-Idempotency-Replayed: true); reusing it with a different request body returns 409 idempotency_conflict. To re-drive a corrected request, mint a new key.

Cuerpo

application/json

The create body. It carries no tenant_id (the tenant is resolved from the JWT). Inline sink_config / credential fields are rejected with 422 inline_sink_config_forbidden — queue credentials arrive only via the credential PUT.

name
string
requerido

A human label for the subscription. Required and non-blank (whitespace-only is rejected).

Ejemplo:

"orders-webhook"

sink_kind
enum<string>
requerido

The delivery destination kind. webhook posts signed HTTPS requests; pull exposes an inbox read over GET /v1/events; sqs, rabbitmq, and eventbridge fan out to the named queue or bus.

Opciones disponibles:
webhook,
pull,
sqs,
rabbitmq,
eventbridge
endpoint
string

The destination address, interpreted per sink kind. For webhook, an https:// URL with no embedded userinfo. For pull, omit it — the server synthesizes a pull://<id> value. For sqs, the https:// queue URL. For rabbitmq, an "<exchange>/<routingKey>" string (exchange required, routing key optional). For eventbridge, the event-bus name / detail-type addressing string. The broker host or AWS region for queue kinds lives in the encrypted credential, not here.

Ejemplo:

"https://hooks.example.com/lerian"

event_types
string[]

The eventKey values to deliver, as GET /v1/catalog serves them. A value the catalog does not list at the schema major the subscription receives it at, from the origin producer when one is set, is refused with 422 unknown_event_type. When the catalog cannot be read or lists no producer event yet, the values are accepted unchecked. Omit the field to receive every event type.

Ejemplo:
origin
string

The ce-source of a producing application.

Ejemplo:

"ledger"

timeout_ms
integer

The per-attempt delivery timeout in milliseconds, from 1000 to 20000. For webhook subscriptions only: the hub refuses a non-zero value for any other sink kind. Omit it, or send 0, to use the 10000 default.

Ejemplo:

20000

schema_major
integer

Optional schema-major pin. Omit it to follow major 1. event_majors overrides it per event type.

Ejemplo:

1

event_majors
object

Optional schema major per event type, overriding schema_major for the types it names. When event_types lists types, each key must be one of them. Each value is from 1 to 2147483647. It cannot be patched: create a new subscription to change it.

plan_tier
string

The plan tier for the subscription.

Ejemplo:

"standard"

Respuesta

The subscription was created. signingSecret carries a secret only for a webhook sink. No read route returns it; a replay of the same X-Idempotency key returns this same response.

The create response. signingSecret carries a secret only for a webhook sink; it is stored only as ciphertext. No read route returns it; a replay of the same X-Idempotency key returns this same response.

subscription
object
requerido

The non-secret projection of a subscription. It never carries the signing secret or any credential material.

signingSecret
string
requerido

The webhook signing secret, minted server-side. No read route returns it; a replay of the same X-Idempotency key returns this same response. An empty string for any other sink kind.

Ejemplo:

"AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8="