Create a subscription

curl --request POST \
  --url https://streaming-hub.sandbox.lerian.net/v1/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "name": "orders-webhook",
  "endpoint": "https://hooks.example.com/lerian",
  "event_types": [
    "transaction.created"
  ],
  "origin": "midaz",
  "timeout_ms": 20000,
  "schema_major": 1,
  "plan_tier": "standard"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://streaming-hub.sandbox.lerian.net/v1/subscriptions"

	payload := strings.NewReader("{\n  \"name\": \"orders-webhook\",\n  \"endpoint\": \"https://hooks.example.com/lerian\",\n  \"event_types\": [\n    \"transaction.created\"\n  ],\n  \"origin\": \"midaz\",\n  \"timeout_ms\": 20000,\n  \"schema_major\": 1,\n  \"plan_tier\": \"standard\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'orders-webhook',
    endpoint: 'https://hooks.example.com/lerian',
    event_types: ['transaction.created'],
    origin: 'midaz',
    timeout_ms: 20000,
    schema_major: 1,
    plan_tier: 'standard'
  })
};

fetch('https://streaming-hub.sandbox.lerian.net/v1/subscriptions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://streaming-hub.sandbox.lerian.net/v1/subscriptions"

payload = {
    "name": "orders-webhook",
    "endpoint": "https://hooks.example.com/lerian",
    "event_types": ["transaction.created"],
    "origin": "midaz",
    "timeout_ms": 20000,
    "schema_major": 1,
    "plan_tier": "standard"
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "subscription": {
    "id": "0192f1a0-0000-7000-8000-00000000c001",
    "name": "orders-webhook",
    "sink_kind": "webhook",
    "endpoint": "https://hooks.example.com/ingest",
    "signature_version": 1,
    "plan_tier": "standard",
    "enabled": true,
    "verification_state": "pending_verification",
    "created_at": "2026-01-15T12:00:00Z",
    "updated_at": "2026-01-15T12:00:00Z",
    "event_types": [
      "account.created",
      "account.updated"
    ],
    "schema_major": 2,
    "origin": "midaz",
    "timeout_ms": 20000
  },
  "signingSecret": "whsec_9f8c2b1e4a7d6055c3e2f10987ab4c21"
}

{
  "title": "Not Found",
  "status": 404,
  "type": "https://errors.lerian.studio/v1/not_found",
  "detail": "subscription not found",
  "code": "not_found"
}

{
  "title": "Not Found",
  "status": 404,
  "type": "https://errors.lerian.studio/v1/not_found",
  "detail": "subscription not found",
  "code": "not_found"
}

{
  "title": "Not Found",
  "status": 404,
  "type": "https://errors.lerian.studio/v1/not_found",
  "detail": "subscription not found",
  "code": "not_found"
}

{
  "title": "Not Found",
  "status": 404,
  "type": "https://errors.lerian.studio/v1/not_found",
  "detail": "subscription not found",
  "code": "not_found",
  "existing_id": "0192f1a0-0000-7000-8000-0000000000ff"
}

{
  "title": "Not Found",
  "status": 404,
  "type": "https://errors.lerian.studio/v1/not_found",
  "detail": "subscription not found",
  "code": "not_found"
}

{
  "title": "Not Found",
  "status": 404,
  "type": "https://errors.lerian.studio/v1/not_found",
  "detail": "subscription not found",
  "code": "not_found"
}

{
  "title": "Not Found",
  "status": 404,
  "type": "https://errors.lerian.studio/v1/not_found",
  "detail": "subscription not found",
  "code": "not_found"
}

Create a subscription

Creates a delivery subscription for the authenticated tenant. A tenant_id in the body is ignored.

A webhook subscription is born pending_verification and mints a signing secret that is returned in this response (see signingSecret); it stays undeliverable until a successful probe via POST /v1/subscriptions/{id}/ping moves it to active. A queue subscription (sqs, rabbitmq, eventbridge) is also born pending_verification and mints no secret; it stays undeliverable until a probe succeeds. Every queue kind activates on an outbound credential supplied and probed via PUT /v1/subscriptions/{id}/credential. An AWS kind (sqs, eventbridge) has a second path that stores no credential: register a delegated grant, then call POST /v1/subscriptions/{id}/verify. Inline sink_config or credential at create is rejected — queue credentials arrive only on the credential PUT.

POST

subscriptions

curl --request POST \
  --url https://streaming-hub.sandbox.lerian.net/v1/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "name": "orders-webhook",
  "endpoint": "https://hooks.example.com/lerian",
  "event_types": [
    "transaction.created"
  ],
  "origin": "midaz",
  "timeout_ms": 20000,
  "schema_major": 1,
  "plan_tier": "standard"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://streaming-hub.sandbox.lerian.net/v1/subscriptions"

	payload := strings.NewReader("{\n  \"name\": \"orders-webhook\",\n  \"endpoint\": \"https://hooks.example.com/lerian\",\n  \"event_types\": [\n    \"transaction.created\"\n  ],\n  \"origin\": \"midaz\",\n  \"timeout_ms\": 20000,\n  \"schema_major\": 1,\n  \"plan_tier\": \"standard\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'orders-webhook',
    endpoint: 'https://hooks.example.com/lerian',
    event_types: ['transaction.created'],
    origin: 'midaz',
    timeout_ms: 20000,
    schema_major: 1,
    plan_tier: 'standard'
  })
};

fetch('https://streaming-hub.sandbox.lerian.net/v1/subscriptions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://streaming-hub.sandbox.lerian.net/v1/subscriptions"

payload = {
    "name": "orders-webhook",
    "endpoint": "https://hooks.example.com/lerian",
    "event_types": ["transaction.created"],
    "origin": "midaz",
    "timeout_ms": 20000,
    "schema_major": 1,
    "plan_tier": "standard"
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "subscription": {
    "id": "0192f1a0-0000-7000-8000-00000000c001",
    "name": "orders-webhook",
    "sink_kind": "webhook",
    "endpoint": "https://hooks.example.com/ingest",
    "signature_version": 1,
    "plan_tier": "standard",
    "enabled": true,
    "verification_state": "pending_verification",
    "created_at": "2026-01-15T12:00:00Z",
    "updated_at": "2026-01-15T12:00:00Z",
    "event_types": [
      "account.created",
      "account.updated"
    ],
    "schema_major": 2,
    "origin": "midaz",
    "timeout_ms": 20000
  },
  "signingSecret": "whsec_9f8c2b1e4a7d6055c3e2f10987ab4c21"
}

{
  "title": "Not Found",
  "status": 404,
  "type": "https://errors.lerian.studio/v1/not_found",
  "detail": "subscription not found",
  "code": "not_found"
}

{
  "title": "Not Found",
  "status": 404,
  "type": "https://errors.lerian.studio/v1/not_found",
  "detail": "subscription not found",
  "code": "not_found"
}

{
  "title": "Not Found",
  "status": 404,
  "type": "https://errors.lerian.studio/v1/not_found",
  "detail": "subscription not found",
  "code": "not_found"
}

{
  "title": "Not Found",
  "status": 404,
  "type": "https://errors.lerian.studio/v1/not_found",
  "detail": "subscription not found",
  "code": "not_found",
  "existing_id": "0192f1a0-0000-7000-8000-0000000000ff"
}

{
  "title": "Not Found",
  "status": 404,
  "type": "https://errors.lerian.studio/v1/not_found",
  "detail": "subscription not found",
  "code": "not_found"
}

{
  "title": "Not Found",
  "status": 404,
  "type": "https://errors.lerian.studio/v1/not_found",
  "detail": "subscription not found",
  "code": "not_found"
}

{
  "title": "Not Found",
  "status": 404,
  "type": "https://errors.lerian.studio/v1/not_found",
  "detail": "subscription not found",
  "code": "not_found"
}

Authorizations

Authorization

string

header

required

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.

Headers

X-Idempotency

string

required

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.

Body

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

required

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

Example:

"orders-webhook"

sink_kind

enum<string>

required

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.

Available options:

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.

Example:

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

event_types

string[]

The eventKey values to deliver, as GET /v1/catalog serves them. Any well-formed key is accepted. A key no producer emits matches nothing.

Example:

["transaction.created"]

origin

string

Pins the subscription to one producing application, by its ce-source. Omit it to receive the event types from any producer.

Example:

"midaz"

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.

Example:

20000

schema_major

integer

Optional schema-major pin. When set, delivery follows the versioned topic for that major; when omitted, the subscription follows the base topic.

Example:

1

plan_tier

string

The plan tier for the subscription.

Example:

"standard"

Response

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

required

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

Show child attributes

signingSecret

string

required

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.

Example:

"whsec_9f8c2b1e4a7d6055c3e2f10987ab4c21"

Catalog

Subscriptions

Event Delivery

Dashboard

Admin

Operational

Error handling

Create a subscription

Authorizations

Headers

Body

Response