Creating a topic

A topic is the publishing destination for a group of subscriptions. Create one per stream of events that shares access rules and delivery defaults, such as order-events or production-alerts. Filters let subscribers select a subset of that stream without requiring another topic.

Create the topic

Select the account and region where publishers and subscribers will operate. Creating a topic requires notifications:CreateTopic; see permissions.

Console
API
CLI
Go

Open Notifications and select Create Topic.
Enter a Name, such as production-alerts.
Optionally enter a Display name and Tags.
Select Create topic. The console opens the topic’s page.

Add recipients from its Subscriptions tab. A topic with no confirmed, matching subscriptions accepts publications but delivers nothing.

Send this request to https://notifications.sa-saopaulo-1.basaltic.sh, with the authentication headers described in Authentication.

POST /v1/topics
Content-Type: application/json

{
  "name": "production-alerts",
  "display_name": "Production alerts",
  "tags": { "environment": "production" }
}

A successful response is HTTP 201, with the resource in topic. Save topic.id for nested subscription, message, and delivery requests. Use topic.crn in IAM policies.

Save the JSON request from the API tab as request-1.json. Use your configured account and region.

basaltic notifications topic create --from-file request-1.json

Save the JSON request from the API tab as request-1.json. Configure credentials, account, and region through the SDK environment variables.

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"

	basaltic "github.com/basaltic-sh/sdk-go"
	"github.com/basaltic-sh/sdk-go/notifications"
)

func readJSON(path string, value any) error {
	data, err := os.ReadFile(path)
	if err != nil {
		return err
	}
	return json.Unmarshal(data, value)
}

func run() error {
	ctx := context.Background()
	cfg, err := basaltic.NewConfig(ctx)
	if err != nil {
		return err
	}
	client := notifications.New(cfg)
	var request1 notifications.CreateTopicRequest
	if err := readJSON("request-1.json", &request1); err != nil {
		return err
	}
	result1, err := client.CreateTopic(ctx, &request1)
	if err != nil {
		return err
	}
	fmt.Printf("%+v\n", result1)
	return nil
}

func main() {
	if err := run(); err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
}

Choose a stable name

Names contain 1–256 ASCII letters, digits, dots, dashes, or underscores and start with a letter or digit. A name must be unique in the account and region. UUID names and the crn: prefix are reserved. The name is immutable and forms the topic CRN, so choose it before writing access policies. The display name is optional and can be changed. It is limited to 100 bytes and is used as the email subject when a publication has no subject.

Delivery defaults

The console creation form uses the platform retry policy. The API accepts a delivery_policy object at creation or in PATCH /v1/topics/{topic_id}:

{
  "delivery_policy": {
    "max_attempts": 6,
    "min_delay_seconds": 20,
    "max_delay_seconds": 1200,
    "timeout_seconds": 15
  }
}

Each subscription can override individual fields. An omitted subscription field inherits the topic’s value, then the platform default. See delivery and retries for the ranges and which failures are retried.

Next steps

Create a subscription, then publish a message. Open the topic’s Metrics tab to observe publishing and delivery rates. Deleting a topic also deletes its subscriptions, published message records, and delivery records.

Get started

Products

Platform

Help

Create the topic

Choose a stable name

Delivery defaults

Next steps

​Create the topic

​Choose a stable name

​Delivery defaults

​Next steps

Create the topic

Choose a stable name

Delivery defaults

Next steps