Skip to main content
Notifications distributes a message from a topic to its subscriptions. Use email for human recipients, webhooks for HTTP integrations, and queue subscriptions for consumers that process messages at their own pace. The service is regional. The endpoint for São Paulo is https://notifications.sa-saopaulo-1.basaltic.sh. Authenticated calls use a bearer token and the account handle in X-Account-Id; see Authentication.

​
Topics and subscriptions

Manage subscriptions at /v1/topics/{topic_id}/subscriptions. The topic is selected by the path; subscription requests and responses do not repeat it. The console lists subscriptions in the topic’s Subscriptions tab. Delivery responses include message and subscription resource references. Each reference has an id and crn; named resources also include name. Messages are listed at /v1/topics/{topic_id}/messages and described at /v1/topics/{topic_id}/messages/{message_id}. Deliveries are also scoped to the topic. The console opens the topics page directly, with Subscriptions, Messages, Deliveries, and Metrics tabs on each topic. Nested message and subscription responses omit the known parent. A subscription’s redrive_policy.dead_letter_queue is a resource reference in responses; requests accept a queue UUID, name, or CRN. Deleting a dead-letter queue preserves its ID and CRN in the reference and omits its name. Confirmation and recipient unsubscribe links belong to the endpoint owner. They are separate from the authenticated subscription management API, which includes deleting subscriptions and resending confirmation requests. A topic has an immutable name. Publishing to it selects confirmed subscriptions whose filter policies match the message. A subscription’s protocol determines how its endpoint is interpreted: Queue destinations and dead-letter targets require queue:SendMessage on the destination queue in addition to the Notifications action. See Notifications permissions.

​
Acceptance and delivery

Publishing returns HTTP 202 after the message is durably queued. This does not mean the subscribers have received it. Use the published message record to inspect fan-out state and delivery records to inspect individual outcomes. Webhook deliveries include an HMAC signature. The signing secret has separate read and rotation permissions; describing a subscription does not grant access to that secret.

​
Metrics

Open a topic’s Metrics tab for publishing, delivery outcomes, success rate, attempt latency, and backlog. The charts use the same time-range controls and Telemetry API as instance metrics. Use the Deliveries tab to inspect a particular failure; metrics do not contain endpoint URLs or message bodies. Series are sampled every 30 seconds. Filter on topic_id and region in Telemetry. Delivery series also carry protocol (email, https, http, or queue). Reading metrics requires telemetry:ReadMetrics in the selected account and region. Use rate for counters. Success rate divides the delivered rate by the terminal outcome rate. Mean latency divides the duration sum rate by the duration count rate. Neither ratio produces a value when its denominator is zero. Counters start when this metrics feature is deployed and persist when message history is removed. Earlier activity is not backfilled. Missing samples indicate no observation, rather than zero activity.

Create a topic

Name a publishing destination and choose delivery defaults.

Create a subscription

Connect email, webhooks, and queues.

Filter policies

Match attributes with worked examples and operator rules.

Publish messages

Send attributed events and follow fan-out.

Delivery and failures

Verify webhooks, configure retries, and retain failed deliveries.

Permissions

IAM actions and cross-service grants.