Boas práticas

Sempre verifique as assinaturas

Sem verificação, qualquer pessoa que descobrir a URL do seu endpoint poderia enviar eventos falsos para disparar ações reais no seu sistema. Nunca processe um payload antes de confirmar seu cabeçalho Synup-Signature.

Lide com entregas duplicadas

Novas tentativas e repetições significam que seu endpoint pode receber o mesmo evento mais de uma vez. Armazene o id do envelope e ignore qualquer evento já processado, em vez de presumir que cada entrega é única.

Responda rápido, processe de forma assíncrona

Retorne um status 2xx assim que confirmar a assinatura e enfileirar o evento — antes de executar lógica lenta, como enviar e-mails ou chamar outras APIs. Uma resposta lenta conta como uma entrega falhada e dispara uma nova tentativa, o que pode fazer você processar o mesmo evento duas vezes.

Assine apenas o que você usa

Reduza os eventos do seu endpoint ao que sua integração realmente processa na aba Eventos. Menos eventos significam menos entregas para proteger, registrar e analisar.

Rotacione sua chave de assinatura periodicamente

Trate sua chave de webhook como qualquer outra credencial. Rotacione-a periodicamente, ou imediatamente se suspeitar que foi exposta — a janela de sobreposição de 7 dias permite implantar a nova chave sem perder entregas.

HTTPS é obrigatório, e seu certificado deve ser válido

Entregas para uma URL com certificado inválido, expirado ou autoassinado falham antes mesmo que o código do seu endpoint seja executado. Use um certificado de uma autoridade confiável — a maioria das plataformas de hospedagem provisiona um automaticamente.