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

# Entrega, novas tentativas e falhas

> Verifique webhooks, configure tentativas e trate envelopes de falhas.

Uma notificação gera um registro de entrega para cada assinatura confirmada cujo filtro corresponda. Novas tentativas atualizam esse registro. Torne o processamento idempotente, por exemplo armazenando o ID da notificação junto à operação concluída.

<span id="webhook-envelopes-and-raw-delivery" />

## Envelopes de webhook e entrega direta

O corpo HTTP padrão é um envelope JSON com `type: "notification"`, `message_id`, `topic_crn`, `topic_name`, `subscription_id`, `message`, `timestamp` e `unsubscribe_url`. Assunto e atributos aparecem quando informados. `message` permanece string mesmo contendo JSON.

Com `raw_message_delivery: true`, o corpo contém o conteúdo selecionado. Metadados ficam nos cabeçalhos `X-Basaltic-Notification-Type`, `X-Basaltic-Message-Id`, `X-Basaltic-Subscription-Id`, `X-Basaltic-Topic-Crn`, `X-Basaltic-Unsubscribe-Url` e `X-Basaltic-Delivery-Attempt`. O tipo continua `application/json`; escolha conteúdo adequado.

Filas sempre recebem o envelope e incluem identificadores da notificação nos atributos. Para FIFO, Notifications deriva o grupo do CRN do tópico e a deduplicação do ID da mensagem publicada. A ordenação FIFO vale dentro da fila; a distribuição assíncrona não garante ordem de publicação.

<span id="verify-webhook-signatures" />

## Verificar assinaturas de webhook

Toda solicitação de webhook assinada inclui:

```text theme={null}
X-Basaltic-Signature: v1,t=<unix-seconds>,s=<hex-hmac-sha256>
```

Use os bytes UTF-8 literais do segredo como chave HMAC. Os bytes assinados são timestamp, ponto e corpo bruto exato. Não interprete e serialize o JSON novamente antes de verificar. Compare em tempo constante e rejeite timestamps mais de cinco minutos no passado ou futuro. Verificar a assinatura não substitui a deduplicação de repetições válidas.

A mesma verificação vale para `subscription_confirmation`. Depois, o proprietário pode seguir `confirm_url` para consentir. Responder com sucesso à solicitação inicial apenas confirma seu recebimento.

Não armazene o segredo em logs. Leitura e rotação exigem permissões separadas. A rotação substitui a chave; coordene com o operador do destino. Descrever ou listar assinaturas nunca retorna o segredo.

<span id="retry-policy" />

## Política de tentativas

| Campo | Padrão | Intervalo | Significado |
| - | - | - | - |
| `max_attempts` | 6 | 1–10 | Total de tentativas, incluindo a primeira. 1 desativa repetições. |
| `min_delay_seconds` | 20 | 1–3,600 | Espera inicial antes de repetir. |
| `max_delay_seconds` | 1,200 | 1–3,600 | Limite da espera exponencial antes da variação aleatória. |
| `timeout_seconds` | 15 | 1–30 | Timeout por tentativa de webhook; ignorado em email. |

A assinatura substitui o tópico por campo. Valores não especificados usam os padrões da plataforma. A espera dobra entre tentativas e inclui variação aleatória; são limites e padrões, não horários exatos. Quando ambos os atrasos são informados, o máximo não pode ser menor que o mínimo.

Em webhooks, HTTP `2xx` significa sucesso. Timeouts, falhas de conexão, HTTP `408`, `429` e `5xx` podem gerar novas tentativas. Outros `4xx` e todos os `3xx` são definitivos; não há redirecionamento. Um destino que resolve para endereço privado bloqueado também falha definitivamente. Sucesso HTTP não prova conclusão da operação de negócio.

<span id="dead-letter-queues" />

## Filas de mensagens não entregues

Defina `redrive_policy.dead_letter_queue` na assinatura para guardar um envelope após falha definitiva. A fila pode ser padrão ou FIFO na mesma conta e região. Configurá-la exige `queue:SendMessage`.

O envelope inclui a notificação original, IDs de assinatura e entrega, tentativas, horário e último erro. O registro continua com falha após redirecionar. Destinos cheios, excluídos ou indisponíveis podem impedir o armazenamento; monitore as falhas e a fila, sem tratá-la como segunda garantia de entrega.

Isso trata falhas ao entregar ao destino. Para um consumidor que recebe mas não processa uma mensagem já enfileirada, configure a [política de redirecionamento](/pt/queue/fifo-and-dead-letter-queues) da fila de destino.

<span id="diagnose-a-missing-notification" />

## Diagnosticar uma notificação ausente

1. Confirme a aceitação da publicação e inspecione a distribuição.
2. Verifique se a assinatura está confirmada.
3. Compare os atributos com toda a política de filtro.
4. Localize a entrega e examine tentativas e último erro.
5. Em webhooks, verifique URL, assinatura e status HTTP.
6. Em filas, verifique disponibilidade, chave de criptografia e concessões dos consumidores.

Use as [métricas Telemetry](/pt/notifications#metrics) para tendências e alertas. Assinaturas filtradas não têm tentativa de entrega com falha. Amostras ausentes indicam lacuna de observação, não ausência comprovada de entregas.


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