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

# Notifications

> Publique em tópicos e entregue notificações a assinaturas de email, webhook e fila.

Notifications distribui mensagens de um tópico às suas assinaturas. Use email para pessoas, webhooks para integrações HTTP e filas para consumidores que processam no próprio ritmo.

O serviço é regional. O endpoint de São Paulo é `https://notifications.sa-saopaulo-1.basaltic.sh`. Chamadas autenticadas usam bearer token e o identificador da conta em `X-Account-Id`; veja [Autenticação](/pt/authentication).

<span id="topics-and-subscriptions" />

## Tópicos e assinaturas

Gerencie assinaturas em `/v1/topics/{topic_id}/subscriptions`. O caminho seleciona o tópico; solicitações e respostas não o repetem. O console lista as assinaturas na aba **Subscriptions** do tópico.

Entregas incluem referências `message` e `subscription`, com `id` e `crn`; recursos nomeados incluem `name`. Liste mensagens em `/v1/topics/{topic_id}/messages` e consulte uma em `/v1/topics/{topic_id}/messages/{message_id}`. Entregas também pertencem ao tópico. O console abre a lista de tópicos, cada um com abas **Subscriptions**, **Messages**, **Deliveries** e **Metrics**. Respostas aninhadas omitem o pai conhecido.

`redrive_policy.dead_letter_queue` é uma referência nas respostas; solicitações aceitam UUID, nome ou CRN da fila. Excluir o destino preserva seu ID e CRN na referência e omite o nome.

Links de confirmação e cancelamento pertencem ao proprietário do destino. São separados da API autenticada de gerenciamento, que permite excluir assinaturas e reenviar confirmações.

O tópico tem nome imutável. A publicação seleciona assinaturas confirmadas cujo filtro corresponde à mensagem. O protocolo determina a interpretação do destino:

| Protocolo | Destino | Confirmação |
| - | - | - |
| `email` | Endereço do destinatário | O destinatário confirma pelo link recebido. |
| `http` ou `https` | URL pública de webhook | O destino confirma o token da solicitação inicial. |
| `queue` | UUID, nome ou CRN da fila na mesma conta e região | Confirmada após resolver e autorizar a fila. |

Destinos de fila e filas de falhas exigem `queue:SendMessage` na fila, além da ação de Notifications. Veja [Permissões do Notifications](/pt/notifications/permissions).

<span id="acceptance-and-delivery" />

## Aceitação e entrega

Publicar retorna HTTP `202` após enfileirar de forma durável. Isso não significa recebimento pelos assinantes. Consulte o registro da mensagem para acompanhar a distribuição e os registros de entrega para resultados individuais.

Webhooks incluem assinatura HMAC. O segredo tem permissões separadas de leitura e rotação; consultar a assinatura não concede acesso ao segredo.

<span id="metrics" />

## Métricas

Abra **Metrics** no tópico para acompanhar publicações, resultados, taxa de sucesso, latência e pendências. Os gráficos usam os controles de tempo e a API Telemetry das métricas de instância. Use **Deliveries** para investigar falhas individuais; métricas não contêm URLs de destino nem corpos.

As séries são amostradas a cada 30 segundos. Filtre por `topic_id` e `region` em [Telemetry](/pt/telemetry#metrics). Séries de entrega também incluem `protocol` (`email`, `https`, `http` ou `queue`). A leitura exige `telemetry:ReadMetrics` na conta e região selecionadas.

| Métrica | Tipo | Significado |
| - | - | - |
| `basaltic_notifications_messages_published_total` | Contador | Notificações aceitas. |
| `basaltic_notifications_bytes_published_total` | Contador | Bytes de corpo aceitos. |
| `basaltic_notifications_messages_pending_fanout` | Gauge | Mensagens aguardando distribuição em entregas. |
| `basaltic_notifications_deliveries_pending` | Gauge | Entregas aguardando resultado definitivo. |
| `basaltic_notifications_delivery_attempts_total` | Contador | Tentativas persistidas, incluindo repetições. |
| `basaltic_notifications_deliveries_delivered_total` | Contador | Resultados definitivos bem-sucedidos. |
| `basaltic_notifications_deliveries_failed_total` | Contador | Falhas definitivas. |
| `basaltic_notifications_delivery_retries_total` | Contador | Tentativas com falha e orçamento para repetir. |
| `basaltic_notifications_delivery_terminal_total` | Contador | Resultados definitivos de sucesso ou falha. |
| `basaltic_notifications_delivery_attempt_duration_seconds_sum` | Contador | Duração total das tentativas persistidas. |
| `basaltic_notifications_delivery_attempt_duration_seconds_count` | Contador | Quantidade de tentativas medidas. |

Use `rate` em contadores. A taxa de sucesso divide entregas bem-sucedidas por resultados definitivos. A latência média divide a taxa da soma de duração pela taxa da contagem. Não há valor quando o denominador é zero. Contadores começam na implantação das métricas e persistem após remover o histórico. Não há preenchimento retroativo. Amostras ausentes representam falta de observação, não atividade zero.

<CardGroup cols={2}>
  <Card title="Criar um tópico" href="/pt/notifications/creating-topics">Name a publishing destination and choose delivery defaults.</Card>
  <Card title="Criar uma assinatura" href="/pt/notifications/creating-subscriptions">Connect email, webhooks, and queues.</Card>
  <Card title="Políticas de filtro" href="/pt/notifications/filter-policies">Match attributes with worked examples and operator rules.</Card>
  <Card title="Publicar mensagens" href="/pt/notifications/publishing">Send attributed events and follow fan-out.</Card>
  <Card title="Entregas e falhas" href="/pt/notifications/delivery">Verify webhooks, configure retries, and retain failed deliveries.</Card>
  <Card title="Permissões" href="/pt/notifications/permissions">IAM actions and cross-service grants.</Card>
</CardGroup>


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