> ## Documentation Index > Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt > Use this file to discover all available pages before exploring further. # Update mutable subscription settings > Protocol and endpoint are immutable — changing either would move deliveries to an address that never completed the confirmation handshake. ## OpenAPI ````yaml /api-reference/specs/notifications.yaml patch /v1/subscriptions/{subscription_id} openapi: 3.0.3 info: title: Basaltic Notifications API version: 1.0.0 description: | Publish/subscribe notification topics with email and webhook delivery. A topic is a fan-out root. Subscriptions bind it to endpoints; publishing to the topic delivers to every confirmed subscription whose filter policy matches the message. **Publishing is asynchronous.** Publish returns 202 as soon as the notification is durable and queued: no delivery has happened yet. Fan-out into per-subscription deliveries runs on a worker, so publish latency does not grow with subscriber count. Poll `GET /v1/messages/{message_id}` for the fan-out state and `GET /v1/deliveries?message_id=...` for per-endpoint outcomes. **Subscriptions must be confirmed.** Subscribe creates the subscription in `pending_confirmation` and sends a token to the endpoint — a link for email, a `subscription_confirmation` POST for webhooks. Nothing is delivered until the endpoint owner presents that token back. The confirmation window is 72 hours; unconfirmed subscriptions are reclaimed after it. If the handshake never arrived, `POST /v1/subscriptions/{id}/resend-confirmation` mints a fresh one — the original token is not recoverable, only its hash is stored. **Webhook endpoints must be publicly routable.** Endpoints resolving to loopback, RFC1918, link-local, or unique-local addresses are refused at subscribe time and again at delivery time. **Webhook deliveries are signed.** Each POST carries `X-Basaltic-Signature: v1,t=,s=`, an HMAC-SHA256 over `"."` keyed by the subscription's signing secret. The secret is returned once by Subscribe and is readable afterwards via the signing-secret endpoint. Verify by recomputing the MAC over the raw body you received — not a re-serialised copy — and reject timestamps more than five minutes from now. contact: name: Basaltic Support email: ping@basaltic.sh license: name: Proprietary url: https://basaltic.sh/terms servers: - url: https://notifications.{region}.basaltic.sh description: Regional API endpoint variables: region: default: sa-saopaulo-1 description: Region code security: - SignatureAuth: [] tags: - name: Topics description: Fan-out topics - name: Subscriptions description: Endpoint subscriptions and their confirmation handshake - name: Messages description: Publishing and delivery status - name: Confirmations description: Unauthenticated endpoint-owner actions paths: /v1/subscriptions/{subscription_id}: parameters: - $ref: '#/components/parameters/SubscriptionId' patch: tags: - Subscriptions summary: Update mutable subscription settings description: | Protocol and endpoint are immutable — changing either would move deliveries to an address that never completed the confirmation handshake. operationId: updateSubscription requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateSubscriptionRequest' responses: '200': description: Updated subscription. content: application/json: schema: $ref: '#/components/schemas/SubscriptionResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' components: parameters: SubscriptionId: name: subscription_id in: path required: true schema: type: string format: uuid example: b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e schemas: UpdateSubscriptionRequest: type: object properties: raw_message_delivery: type: boolean example: true filter_policy: $ref: '#/components/schemas/FilterPolicy' delivery_policy: $ref: '#/components/schemas/DeliveryPolicy' redrive_policy: allOf: - $ref: '#/components/schemas/RedrivePolicy' description: | Omitted leaves the dead-letter queue unchanged. Present with an empty `dead_letter_queue` clears it. Setting a new target re-checks `queue:SendMessage` on it. tags: $ref: '#/components/schemas/Tags' SubscriptionResponse: type: object required: - subscription properties: subscription: $ref: '#/components/schemas/Subscription' FilterPolicy: type: object description: | Restricts which messages reach a subscription, matched against message attributes. Every named attribute must match at least one of its alternatives (AND across names, OR within a name). An omitted or empty policy matches everything. An alternative is a literal string, or one of: `{"prefix": "..."}`, `{"suffix": "..."}`, `{"anything-but": [...]}`, `{"exists": true|false}`, `{"numeric": [">=", 0, "<", 100]}`. Only `exists` can match an attribute that is absent; every other form requires a value to compare. additionalProperties: type: array items: {} example: severity: - critical - error region: - prefix: sao latency: - numeric: - '>' - 100 tenant: - exists: true DeliveryPolicy: type: object description: | 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. properties: max_attempts: type: integer minimum: 1 maximum: 10 description: Total attempts including the first. 1 disables retries. example: 6 min_delay_seconds: type: integer minimum: 1 maximum: 3600 description: Backoff before the second attempt. example: 20 max_delay_seconds: type: integer minimum: 1 maximum: 3600 description: Cap on the exponential curve. example: 1200 timeout_seconds: type: integer minimum: 1 maximum: 30 description: Per-request timeout. Ignored for email. example: 15 RedrivePolicy: type: object required: - dead_letter_queue description: | 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 are visible only via the delivery records and the delivery-statistics endpoints. 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. properties: dead_letter_queue: type: string description: The target queue's CRN. example: crn:queue:sa-saopaulo-1:my-account:queue/notification-failures Tags: type: object additionalProperties: type: string example: environment: production team: backend Subscription: type: object required: - id - crn - topic_id - protocol - endpoint - status - raw_message_delivery - created_at - updated_at properties: id: type: string format: uuid example: b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e crn: type: string example: >- crn:notifications:sa-saopaulo-1:my-account:subscription/b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e topic_id: type: string format: uuid example: a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d protocol: type: string enum: - email - https - http - queue example: https endpoint: type: string description: Immutable. An email address, or an http/https URL. example: https://hooks.example.com/basaltic status: type: string enum: - pending_confirmation - confirmed example: confirmed raw_message_delivery: type: boolean description: >- http/https only. Deliver the published payload verbatim instead of the notification envelope; the metadata moves into headers. example: false filter_policy: $ref: '#/components/schemas/FilterPolicy' delivery_policy: $ref: '#/components/schemas/DeliveryPolicy' redrive_policy: $ref: '#/components/schemas/RedrivePolicy' confirmation_expires_at: type: string format: date-time nullable: true description: When the pending confirmation lapses. Absent once confirmed. example: '2026-01-21T09:30:00Z' confirmed_at: type: string format: date-time nullable: true example: '2026-01-18T09:31:00Z' tags: $ref: '#/components/schemas/Tags' created_at: type: string format: date-time example: '2026-01-18T09:30:00Z' updated_at: type: string format: date-time example: '2026-01-18T09:31:00Z' Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string description: Error code identifying the type of error example: INVALID_INPUT message: type: string description: Human-readable error message example: Invalid request parameters request_id: type: string format: uuid description: Request ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 responses: BadRequest: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_INPUT message: Invalid request parameters request_id: 550e8400-e29b-41d4-a716-446655440000 Unauthorized: description: Authentication required or token invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Authentication required request_id: 550e8400-e29b-41d4-a716-446655440000 Forbidden: description: Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ACCESS_DENIED message: You don't have permission to perform this action request_id: 550e8400-e29b-41d4-a716-446655440000 NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: NOT_FOUND message: Resource not found request_id: 550e8400-e29b-41d4-a716-446655440000 securitySchemes: SignatureAuth: type: apiKey in: header name: Authorization description: > Request signing with an access key issued to a service account. An HMAC-SHA256 over a canonical form of the request, close to AWS SigV4. The `basaltic` CLI signs for you. Send `Authorization`, `X-Date` (UTC, `YYYYMMDDTHHMMSSZ`) and `X-Nonce` (random per request); add `X-Content-Sha256` to bind a body, and `X-Amz-Security-Token` when using temporary credentials. ``` Authorization: BASALTIC-HMAC-SHA256 Credential=///basaltic/basaltic_request, SignedHeaders=host;x-date;x-nonce, Signature= ``` `` is the region code you are calling, or `global` for the global services. A signature is valid for 5 minutes from `X-Date`, and mutating requests are replay-guarded on the nonce. **Full signing procedure, including a working implementation:** https://docs.basaltic.sh/authentication ## Rate limits There is no global request budget. A limit applies only where an operation documents a `429`, and that operation says what it counts. Those responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and, on a `429`, `Retry-After` — read them rather than hard-coding a number. Retrying before `Retry-After` is refused and extends the window. Everything else is bounded by quota, not by request rate. ````