Skip to main content
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.

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

​
Verificar assinaturas de webhook

Toda solicitação de webhook assinada inclui:
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.

​
Política de tentativas

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.

​
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 da fila de destino.

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