---
title: Segurança
description: Como validar e proteger payloads de webhook do IDCloud — verificação de assinatura e boas práticas.
canonical: https://developer.unico.io/pt-BR/dual-api/developers/webhooks-and-events/security
locale: pt-BR
generated_by: markdown-export
---

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.

```javascript
// 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();
}
```

:::warning[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.