Entrega e novas tentativas
O que conta como entrega bem-sucedida, quanto tempo o BreezeAuth espera pelo seu endpoint e como as entregas que falham são repetidas.
Esta página explica o que acontece entre o momento em que um evento ocorre na sua organização e o momento em que o seu endpoint confirma o recebimento, incluindo o que o BreezeAuth faz quando algo dá errado.
Entrega
Quando um evento ocorre, o BreezeAuth o envia, normalmente em poucos segundos, a todos os webhooks ativados da
organização que assinam aquele tipo de evento. Cada entrega é uma requisição HTTP POST para a URL do webhook, com a
mensagem no corpo em JSON e os cabeçalhos de assinatura.
O que conta como sucesso
Uma tentativa é bem-sucedida somente quando o seu endpoint responde com um status 2xx (de 200 a 299) em até
15 segundos. Qualquer outra coisa é uma falha:
| O que o seu endpoint faz | Resultado |
|---|---|
Responde 2xx em até 15 segundos |
✅ Sucesso. O corpo da resposta é ignorado. |
Responde com um redirecionamento (301, 302, 307, 308…) |
❌ Falha. Redirecionamentos não são seguidos. Cadastre a URL final. |
Responde 4xx (como 400, 401, 404) |
❌ Falha. |
Responde 5xx (como 500, 502, 503) |
❌ Falha. |
| Demora mais de 15 segundos para responder | ❌ Falha (tempo esgotado). O seu endpoint pode ter processado a mensagem mesmo assim, então espere uma duplicata. |
| Não pode ser alcançado (erro de DNS, conexão recusada, certificado TLS inválido) | ❌ Falha. |
Importante: respostas 3xx são tratadas como erro. Uma causa comum é cadastrar http:// quando o servidor
redireciona para https://, ou omitir uma barra final que o servidor exige. Use a URL final exata.
Novas tentativas
Quando uma tentativa falha, o BreezeAuth tenta de novo. Cada evento tem até 3 tentativas por webhook: a entrega original e mais 2 novas tentativas.
| Tentativa | Quando acontece |
|---|---|
| 1 | Logo após o evento ocorrer. |
| 2 | Cerca de 5 segundos depois que a tentativa 1 falhou. |
| 3 | Cerca de 30 segundos depois que a tentativa 2 falhou. |
Se a terceira tentativa também falhar, o BreezeAuth desiste daquele evento para aquele webhook. Contando o tempo limite de 15 segundos de cada tentativa, todas acontecem em cerca de um minuto e meio após o evento.
Todas as tentativas levam exatamente a mesma mensagem: o mesmo webhook-id, o mesmo webhook-timestamp e o mesmo
corpo. É isso que permite ao seu endpoint reconhecer duplicatas.
Observação: a janela de novas tentativas é curta de propósito. Os webhooks servem para avisar você rapidamente sobre mudanças, e não para acumular mensagens para um endpoint fora do ar. Se o seu endpoint puder ficar indisponível por mais tempo, adicione uma reconciliação periódica pela API.
Alterações de configuração durante as novas tentativas
Antes de cada tentativa, o BreezeAuth lê a configuração atual do webhook:
- se o webhook foi desativado, ou se o tipo de evento foi removido das assinaturas, as tentativas restantes são canceladas;
- se a URL foi alterada, a próxima tentativa vai para a nova URL.
Garantias de entrega
- Pelo menos uma vez. O BreezeAuth faz todo o possível para entregar cada evento e, em algumas situações, pode entregar o mesmo evento mais de uma vez. O seu endpoint precisa ignorar duplicatas.
- Sem garantia de ordem. Os eventos são entregues de forma independente e as novas tentativas adicionam atrasos, então as mensagens podem chegar em ordem diferente da dos eventos. Leia o estado atual na API em vez de depender da ordem.
- Uma mensagem por evento. Cada mensagem descreve exatamente um evento; não há agrupamento.
Quando as entregas falham
Cada tentativa, bem-sucedida ou não, fica registrada no Histórico de eventos do webhook, com o status ou o erro que causou a falha. Veja Histórico de eventos para investigar problemas.
Última atualização: 13 de outubro de 2026