Segurança

A confiabilidade do webhook depende tanto do comportamento do seu endpoint quanto das garantias de entrega da Unico. Esta página aborda os três invariantes que o seu endpoint deve respeitar: idempotência, limite de concorrência e taxa de erros.

Idempotência

A implementação de webhook da Unico garante entrega pelo menos uma vez — o mesmo status pode ser notificado mais de uma vez para o mesmo processId. O seu endpoint deve ser idempotente.

Padrão recomendado:

1. A cada chamada de webhook, verifique primeiro se o processId já foi processado.
2. Se já foi, retorne 2xx imediatamente (o trabalho já está feito).
3. Se não, aplique sua lógica de negócio e persista o fato de que este processId foi processado.

// pseudo-code
async function handleWebhook(req, res) {
  const { processId } = req.body;

  if (await alreadyProcessed(processId)) {
    return res.status(200).end();
  }

  await applyBusinessLogic(req.body);
  await markAsProcessed(processId);
  return res.status(200).end();
}

Por que isso importa

Um endpoint não-idempotente que executa lógica de negócio a cada entrega (ex.: cobra um cartão, envia um e-mail) vai disparar múltiplas vezes quando houver uma retentativa — e retentativas são normais, não excepcionais, na entrega de webhooks.

Limite de concorrência

Para proteger o seu endpoint de picos durante períodos de alto volume, configure um número máximo de entregas simultâneas em andamento (máx: 500) ao registrar o webhook.

Quando o limite de concorrência é atingido, a Unico enfileira as entregas adicionais e as processa conforme a capacidade fica disponível. Combinado com retentativas, isso significa que um pico sustentado pode aumentar o tempo efetivo de entrega de novos webhooks.

Taxa de erros

A taxa de erros (respostas fora da faixa 200–299) deve ser sempre baixa. Se o seu endpoint começar a retornar erros em escala, a Unico reduz automaticamente o throughput do webhook para aquele endpoint. Combinado com o mecanismo de retry, isso pode aumentar significativamente o tempo de execução de novos webhooks.

Orientações operacionais:

• Monitore respostas não-2xx do seu lado. Alerte sobre taxas de erro sustentadas acima da sua linha de base normal.
• Trate o seu handler de webhook como um caminho crítico — ele deve ser um dos serviços mais confiáveis da sua stack.
• Para manutenção planejada, prefira interromper a recepção no load balancer em vez de retornar 503. Respostas não-2xx sustentadas — incluindo 503 — ativam o throttling automático de throughput descrito acima; quando o endpoint se recupera, o throughput reduzido atrasa a entrega dos eventos que se acumularam durante a indisponibilidade. Não retorne 200 para eventos não processados.

Semântica de status

Trate o conjunto de valores de state e lastEvent como configuração evoluível:

• Reaja apenas a estados / eventos que você trata explicitamente.
• Registre valores desconhecidos em log — não gere erro para eles.
• Novos estados podem ser adicionados sem uma mudança de versão maior.