> ## 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.

# Criando uma assinatura

> Conecte email, webhook ou fila a um tópico e escolha as mensagens recebidas.

Crie assinaturas pelo tópico. Protocolo e destino são fixos; alterá-los exige outra assinatura para autorizar ou confirmar o novo destino.

<span id="choose-the-destination" />

## Escolha o destino

| Protocolo | Destino | Início da entrega |
| - | - | - |
| `email` | Endereço de email | Após abrir o link de confirmação. |
| `https` | URL HTTPS pública | Após o proprietário confirmar a solicitação inicial assinada. |
| `http` | URL HTTP pública | Após o proprietário confirmar a solicitação inicial assinada. |
| `queue` | Nome, UUID ou CRN da fila | Imediatamente após autorizar a fila. |

Prefira HTTPS. O esquema da URL deve corresponder ao protocolo. Loopback, destinos privados e link-local são recusados. Redirecionamentos não são seguidos. Filas devem estar na mesma conta e região e exigem `queue:SendMessage` no destino e `notifications:Subscribe` no tópico.

<span id="create-the-subscription" />

## Criar a assinatura

<Tabs>
  <Tab title="Console">
    1. Abra **Notifications**, escolha o tópico e abra **Subscriptions**.
    2. Selecione **Subscribe** para abrir a criação.
    3. Escolha **Protocol** e informe **Endpoint**.
    4. Opcionalmente informe **Filter policy** e **Dead-letter queue**.
    5. Para webhook, ative **Raw message delivery** somente se o destino espera o conteúdo publicado sem envelope.
    6. Selecione **Create subscription**.

       Em um novo webhook, salve o segredo exibido para o operador do destino. Ao fechar o diálogo, o console abre a assinatura. Email e fila abrem a página diretamente.
  </Tab>

  <Tab title="API">
    ```http theme={null}
    POST /v1/topics/{topic_id}/subscriptions
    Content-Type: application/json
    ```

    ```json theme={null}
    {
      "protocol": "queue",
      "endpoint": "order-workers",
      "filter_policy": {
        "event": ["order.created", "order.paid"]
      },
      "redrive_policy": {
        "dead_letter_queue": "notification-failures"
      }
    }
    ```

    HTTP `201` retorna um objeto `subscription`. Filas são resolvidas e retornadas como CRNs. O tópico é informado na URL e não se repete na solicitação nem na resposta.

    Para webhook, defina `protocol` como `https` e `endpoint` como uma URL pública. A primeira criação também retorna `signing_secret`. Repetir tópico, protocolo e destino retorna a assinatura existente sem emitir outro segredo; use PATCH para alterar configurações.
  </Tab>

  <Tab title="CLI">
    Salve a solicitação JSON da aba API como `request-1.json`. Defina `TOPIC_ID` com o UUID do recurso. Use sua conta e região configuradas.

    ```bash theme={null}
    basaltic notifications subscription subscribe "$TOPIC_ID" --from-file request-1.json
    ```
  </Tab>

  <Tab title="Go">
    Salve a solicitação JSON da aba API como `request-1.json`. Defina `TOPIC_ID` com o UUID do recurso. Configure credenciais, conta e região pelas variáveis de ambiente do SDK.

    ```go theme={null}
    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.SubscribeRequest
    	if err := readJSON("request-1.json", &request1); err != nil {
    		return err
    	}
    	result1, err := client.Subscribe(ctx, os.Getenv("TOPIC_ID"), &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)
    	}
    }
    ```
  </Tab>
</Tabs>

<span id="confirmation" />

## Confirmação

Email e webhooks começam em `pending_confirmation`. Links vencem após 72 horas por padrão. Use a ação de reenvio se o link vencer. O proprietário segue o link recebido; responder HTTP `200` à solicitação inicial do webhook não confirma sozinho.

Links do destinatário são separados do gerenciamento autenticado e não são operações SDK ou CLI. O destinatário também pode usar o link de cancelamento da notificação. Administradores removem assinaturas pela operação DELETE autenticada.

<span id="filtering-and-delivery-options" />

## Filtros e opções de entrega

Um filtro omitido ou vazio recebe todas as publicações. Uma política preenchida compara somente [atributos da mensagem](/pt/notifications/filter-policies), não campos de um corpo JSON. As políticas valem para todos os protocolos.

`raw_message_delivery` só é permitido em HTTP e HTTPS. Filas sempre recebem o envelope. `delivery_policy` permite substituir os campos da política de tentativas do tópico pela API.

A fila de falhas da assinatura recebe envelopes de entregas de notificação malsucedidas. É diferente da política de uma fila, que trata mensagens concedidas repetidamente sem confirmação. Veja [falhas de entrega](/pt/notifications/delivery#dead-letter-queues).

<span id="change-or-delete-a-subscription" />

## Alterar ou excluir uma assinatura

Atualize configurações em `PATCH /v1/topics/{topic_id}/subscriptions/{subscription_id}`. Omitir `filter_policy` preserva o filtro; um objeto vazio o remove. Protocolo e destino são imutáveis. Exclua o mesmo caminho para interromper futuras entregas. Leia ou rotacione segredos pelas ações específicas, com permissões separadas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.