Webhooks de status de SMS: segurança, fiabilidade e rastreabilidade

O que comunica um webhook de status de SMS e o que não comprova

Um webhook é um mecanismo através do qual um sistema envia automaticamente eventos para outro. Numa integração de SMS, o fornecedor pode comunicar estados relacionados com as mensagens, mas o evento exato, os respetivos campos e o seu significado dependem da documentação e do contrato desse fornecedor. A informação técnica disponível não comprova a existência de um esquema comum de estados de SMS aplicável a todos os fornecedores.

Este guia apresenta princípios de conceção, não uma especificação de fornecedor. Como referência geral sobre webhooks, a documentação da emBlue descreve a sua utilização para receber automaticamente eventos de comunicações em sistemas próprios; essa informação não documenta estados de SMS nem o comportamento de um fornecedor específico de SMS. Consulte sempre a documentação oficial do fornecedor da sua integração.

Convém distinguir três factos: o callback chegou ao seu endpoint, o fornecedor comunicou um estado e existe evidência independente de receção no terminal. Registar o primeiro não comprova o segundo; um estado comunicado também não comprova, por si só, o terceiro. Preserve essa distinção nos relatórios e na lógica de negócio.

• Documente o significado de cada estado segundo a definição oficial do fornecedor.
• Registe a origem dos dados e evite classificar como «verificada» uma entrega que apenas consta como comunicada pelo fornecedor.
• Quando não puder confirmar a receção no terminal, indique essa incerteza em vez de inferir uma garantia.

Modelo de ameaças: falsificação, repetição, saturação e perda

Um endpoint de callback exposto à Internet pode receber pedidos inesperados, eventos repetidos ou um volume que exceda a sua capacidade. Também pode deixar de receber eventos devido a falhas de rede ou do sistema emissor. A evidência disponível não permite atribuir a todos os fornecedores uma política comum de autenticação, limites, novas tentativas ou retenção; verifique cada ponto na documentação oficial e no contrato de integração.

Conceba controlos para detetar pedidos inválidos e proteger a disponibilidade, mas evite considerar um evento autêntico apenas porque provém de um endereço IP conhecido. Os endereços e intervalos podem mudar e só são um controlo útil quando o fornecedor documenta como os manter.

• Identifique o mecanismo documentado que permite autenticar ou validar o pedido.
• Consulte os limites de tamanho e frequência, os tempos de espera e a política de novas tentativas antes de definir os seus limiares.
• Defina alertas para picos de tráfego, erros de validação e períodos sem os eventos esperados.

Validar a origem e a autenticidade sem presumir capacidades

A autenticação deve corresponder ao que o fornecedor realmente disponibiliza e documenta. Se fornecer um mecanismo verificável, como uma assinatura ou credencial para callbacks, siga a respetiva especificação e proteja os segredos. Não se deve afirmar que existe uma assinatura, uma lista de IP fiável ou um formato universal de autenticação para webhooks de SMS.

Se o fornecedor não documentar um método suficiente para validar a origem, peça esclarecimentos antes de tratar os eventos como fiáveis. Mantenha o endpoint limitado à função de receção e não inclua credenciais sensíveis no URL.

O endpoint deve usar HTTPS para proteger os dados durante a transmissão. Por si só, o HTTPS não autentica o emissor: valide também o pedido através do mecanismo documentado pelo fornecedor.

• Confirme na documentação oficial que dados de autenticação são enviados e como devem ser validados.
• Aplique a validação de IP apenas se o fornecedor publicar o método e os intervalos em vigor, e defina como os atualizar.
• Rejeite pedidos que não cumpram o mecanismo acordado e registe o motivo sem armazenar segredos.
• Use HTTPS no endpoint; não o trate como prova da identidade do emissor.

Receção robusta: validar e responder sem bloquear o processamento

Separe a receção do trabalho posterior. O endpoint pode validar o formato e os campos necessários, guardar o evento de forma duradoura e colocá-lo numa fila para que outros processos atualizem estados ou gerem alertas. A resposta deve ser rápida, mas o código de sucesso e o prazo aceites dependem do contrato do fornecedor: confirme-os antes de os implementar.

Valide o tipo de conteúdo, o esquema e os campos obrigatórios documentados. Aplique limites de tamanho e frequência adequados ao contrato e à sua capacidade. Não invente limites universais: a informação técnica disponível não estabelece tamanhos máximos nem taxas comuns para callbacks de SMS.

• Verifique a estrutura e os valores aceites de acordo com a especificação do fornecedor.
• Guarde o evento original ou uma representação segura antes de confirmar a receção.
• Envie o processamento intensivo para uma fila e monitorize erros, acumulação e antiguidade das mensagens.
• Ajuste os códigos de resposta, os tempos de espera e os limites ao que está documentado; teste a resposta do emissor em cada situação.

Idempotência e deduplicação com os identificadores disponíveis

O mesmo evento pode surgir mais do que uma vez, devido a novas tentativas ou a outras condições de entrega, mas não se pode presumir que todos os fornecedores repitam eventos ou incluam um identificador globalmente único. Analise o esquema oficial para saber que identificadores existem, qual é o seu âmbito e que garantias oferecem.

Se existir um identificador de evento documentado, utilize-o como parte de uma chave de deduplicação dentro do âmbito especificado pelo fornecedor. Se não existir, uma impressão digital criada a partir de campos estáveis pode ajudar, mas não comprova que dois registos são idênticos nem substitui uma garantia do fornecedor. Preserve o evento recebido e registe quando uma decisão de deduplicação é heurística.

• Não utilize um identificador de mensagem como identificador de evento sem confirmar o seu significado.
• Faça com que as atualizações de estado repetidas sejam seguras e não dupliquem efeitos secundários.
• Registe a chave utilizada e o motivo pelo qual um evento foi aceite, marcado como repetido ou deixado pendente para revisão.

Eventos duplicados, atrasados ou fora de ordem

Não presuma que os eventos chegam apenas uma vez ou pela ordem em que ocorreram. A documentação disponível não comprova garantias gerais de ordenação para webhooks de SMS. Preserve cada evento com a respetiva hora de receção e, quando o fornecedor a incluir, com a marca temporal do evento; não confunda as duas marcas.

Defina regras explícitas para determinar um estado efetivo. Por exemplo, documente que transições o seu sistema aceita e como trata um evento atrasado que parece contradizer um evento posterior. Se a semântica dos estados não for clara, preserve a sequência observada e assinale o resultado como incerto, em vez de inventar uma ordem definitiva.

• Armazene o histórico de eventos, não apenas o último valor substituído.
• Separe a hora indicada pelo fornecedor da hora em que o seu sistema recebeu o callback.
• Teste duplicados, eventos atrasados e sequências contraditórias com regras que possam ser revistas.

Novas tentativas e tratamento de falhas

As novas tentativas podem ocorrer no emissor ou no seu sistema, mas a sua existência, duração, intervalos e condições dependem do fornecedor e do contrato. Não presuma que um callback falhado será reenviado ou que as novas tentativas serão indefinidas. Verifique que respostas HTTP são consideradas satisfatórias, durante quanto tempo se repetem as tentativas e o que acontece quando estas se esgotam.

Do seu lado, estabeleça uma política para erros temporários e permanentes. Utilize intervalos progressivos e limites de novas tentativas adequados à sua operação, registe os eventos que não puderam ser processados e defina um procedimento de revisão ou reprocessamento. Estas são decisões de conceção do seu sistema, não garantias do emissor.

• Peça e registe a política oficial de novas tentativas do fornecedor, incluindo o que acontece quando se esgotam.
• Distinga falhas de validação, erros temporários de infraestrutura e falhas permanentes de processamento.
• Evite novas tentativas ilimitadas; estabeleça limites, alertas e uma fila de revisão para os casos não resolvidos.
• Assegure-se de que reprocessar um evento não duplica ações de negócio.

Observabilidade e reconciliação sem exagerar o nível de verificação

Meça a saúde do fluxo com indicadores que possa observar diretamente: callbacks recebidos, rejeitados e processados; atrasos entre receção e processamento; eventos duplicados; erros e elementos pendentes. Interprete qualquer comparação com estados das mensagens tendo em conta o âmbito dos registos e a semântica definida pelo fornecedor.

Se o fornecedor disponibilizar uma consulta de estados ou um relatório de eventos, confirme a respetiva disponibilidade, cobertura e regras de retenção na documentação oficial antes de conceber uma reconciliação. A informação técnica disponível não confirma a existência de um método de consulta comum. Uma comparação pode assinalar discrepâncias, mas não comprova, por si só, o que aconteceu no terminal.

• Defina alertas para interrupções na receção, acumulação da fila, aumento de erros e eventos por processar.
• Compare apenas fontes cujos identificadores, períodos e significados sejam compatíveis.
• Classifique cada resultado de acordo com a evidência: receção do callback, estado comunicado ou verificação independente.
• Documente as discrepâncias que não consegue resolver com os dados disponíveis.