Guia · Webhooks
Webhooks de SMS: assinatura, idempotência e segurança
Um webhook é entrada não confiável até que assinatura, timestamp e contrato sejam validados. A resposta 2xx deve ocorrer depois que o consumidor puder recuperar o evento com segurança.
Valide antes de interpretar
Leia o corpo bruto, extraia timestamp e assinatura e só então faça parse do JSON. Serializar o objeto novamente pode mudar bytes e invalidar uma verificação correta.
Reduza risco de replay
Rejeite timestamps com diferença superior a cinco minutos e persista event_id. Use comparação constante para assinaturas e mantenha segredos separados entre Sandbox e Produção.
Persista antes de responder
Uma resposta 2xx encerra a tentativa do emissor. Grave o evento ou uma referência durável antes de confirmar. Processamento pesado pode seguir de forma assíncrona.
Planeje rotação de segredo
Durante uma janela curta, aceite o segredo atual e o próximo. Identifique qual versão validou a assinatura sem registrar os valores dos segredos.