Skip to main content
POST
Subscribe an endpoint to a topic
Requires the IAM action notifications:Subscribe. See NOTIFICATIONS permissions for the full list, what each one covers, and an example policy.

Authorizations

Authorization
string
header
required

An OAuth 2.0 bearer token, sent as Authorization: Bearer <token>. This is the recommended way to authenticate.

Get one by exchanging a service account's access key pair at POST /v1/oauth/token with grant_type=client_credentials. It is the standard client-credentials grant, so any OAuth-aware library will obtain and refresh it for you.

Tokens last an hour by default. The same access key pair is separately your AWS SigV4 credential for the S3-compatible object endpoint, which speaks nothing else.

Headers

Idempotency-Key
string

Optional client-generated key that makes a create replay-safe. Retrying a request with the same key returns the original outcome verbatim instead of creating a duplicate resource. Reusing a key with a different request body is rejected (422); a request whose key is still being processed returns 409. Records are honored for 24 hours. Use a UUID or similarly unique token.

Maximum string length: 255

Path Parameters

topic_id
string<uuid>
required
Example:

"a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"

Body

application/json
protocol
enum<string>
required
Available options:
email,
https,
http,
queue
Example:

"https"

endpoint
string
required

An email address; an http/https URL whose scheme matches the protocol and resolves to a publicly-routable address; or, for queue, a queue UUID, CRN or exact name in the subscriber account and serving region. Queue targets are stored and returned as canonical CRNs.

A queue subscription skips the confirmation handshake and is created already confirmed. The handshake exists to prove that whoever controls the endpoint consents to receive, which is necessary for an address or a URL you may not own. A queue is your own resource, so consent is established instead by requiring queue:SendMessage on it at subscribe time — an authorization decision rather than a demonstration of reachability.

Maximum string length: 2048
Example:

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

raw_message_delivery
boolean
default:false

http/https only.

Example:

false

filter_policy
object

Matches publication attributes, not fields inside the message body. Every named attribute must match at least one alternative (AND across names, OR within each array). Names and string comparisons are case-sensitive. An omitted or empty policy matches every message.

Alternatives are exact strings or numbers, or single-operator objects: {"prefix": "order."}, {"suffix": ".failed"}, {"anything-but": ["debug", "trace"]}, {"exists": true}, {"exists": false}, or {"numeric": [">=", 100, "<", 1000]}. Prefix and suffix values must be nonempty. anything-but accepts one string or number, or a list of 1–50 such values.

Only exists: false matches an absent attribute. Exclusion also requires presence. Numeric operators are =, <, <=, >, and >=; every operator/number pair in one numeric matcher must succeed. Attribute values that cannot be parsed as numbers do not match. Bare numeric alternatives compare string representations; use numeric for numeric equality, such as matching both "100" and "100.0".

At most 20 nonblank attribute names and 1–50 alternatives per name. Each operator object has exactly one operator. Wildcards, regular expressions, body filtering, and nested operators are not supported. PATCH replaces the entire policy; {} clears it and omission preserves it. See Filter policies for worked examples.

Example:
delivery_policy
object

Retry behaviour. Omitted fields fall back to the topic's policy, then to platform defaults (6 attempts, 20s to 20m exponential backoff with jitter, 15s per-request timeout). A subscription's policy is layered on its topic's field by field, so overriding only max_attempts keeps the topic's backoff curve.

redrive_policy
object

Names a queue in the subscriber's own account that receives each terminally failed delivery — the full original notification plus a failure block (delivery id, endpoint, attempts, last error, status code) — as a delivery_failure message. Without one, terminal failures remain visible in delivery records and Telemetry metrics.

The caller must hold queue:SendMessage on the target when the policy is set: writes happen later with no principal present, so consent is established up front, exactly as for a protocol=queue endpoint. For a queue subscription the target must differ from the endpoint queue.

tags
object
Example:

Response

Subscription created (or the existing one returned).

subscription
object
required
signing_secret
string

The HMAC key for verifying webhook deliveries. Returned only on the first create of an http/https subscription — absent for email, and absent when an existing subscription is returned.

Example:

"kJ8vQ2xR5tY7uI0oP3aS6dF9gH1jK4lZ7xC0vB3nM6Q"