Entregas e retentativas
Saiba o que conta como entrega bem-sucedida, quantas tentativas a PagPolar faz e como reenviar avisos pelo painel.
O que conta como entrega bem-sucedida
A entrega dá certo quando o seu servidor responde com qualquer status 2xx (200, 201, 202, 204...) em até 10 segundos. Passado esse tempo, a tentativa conta como falha, mesmo que o seu servidor termine o processamento depois.
O corpo da resposta não importa. Responda 200 com corpo vazio.
Por isso: grave o evento, responda e processe em seguida. Veja Responda rápido e processe depois.
Novas tentativas
Quando a entrega falha por erro passageiro, a PagPolar tenta de novo: status fora de 2xx (exceto 404 e 410), conexão recusada ou tempo esgotado.
| Webhook | Máximo de tentativas | Intervalo entre tentativas |
|---|---|---|
| Webhook da credencial | 5, até você mudar Máximo de tentativas em Configurações → Webhooks (de 1 a 10) | Cerca de 30 segundos |
| Webhooks adicionais | O valor de Máximo de tentativas, de 1 a 10 (padrão 5) | Cerca de 30 segundos |
O número de tentativas conta a primeira. Exemplo com 5 tentativas: a primeira falha e chegam mais 4, uma a cada 30 segundos, mais ou menos. Depois da quinta falha, o envio para e o webhook é desativado.
As novas tentativas automáticas vão para a mesma URL e com o mesmo token do primeiro envio. O corpo é montado de novo em cada tentativa, com o estado daquele momento.
Quando o webhook é desativado
Alguns erros mostram que a URL não vai funcionar sem uma correção sua. Nesses casos a PagPolar desativa o webhook na hora, sem novas tentativas, e grava o motivo no webhook:
| Situação | Motivo gravado |
|---|---|
Seu servidor respondeu 404 ou 410 | URL não encontrada (404) ou (410) |
| O domínio da URL não existe | Domínio não encontrado |
| A URL é inválida | URL inválida |
| O certificado SSL é inválido, expirado ou autoassinado | Certificado SSL inválido |
| Um envio esgotou as tentativas | Falha após N tentativas, com o último erro |
O motivo começa com Webhook desativado automaticamente. Isso vale também para o webhook da credencial.
Com o webhook desativado, os envios que ainda estavam na fila são descartados e os eventos seguintes não são enviados. O mesmo acontece ao revogar a credencial.
Para voltar a receber, corrija a URL ou o seu servidor e ative o webhook de novo em Configurações → Webhooks. Ao reativar, o motivo é apagado. Os avisos perdidos no período podem ser reenviados pelo painel, como mostra a seção abaixo; o reenvio só entrega com o webhook ativo.
Histórico de envios no painel
Há dois lugares para ver os envios:
| Tela | Como abrir | O que mostra |
|---|---|---|
| Envios | Configurações → Webhooks, aba Envios | Os envios de todos os webhooks da conta. |
| Logs do Webhook | Em Configurações → API, clique no ícone Ver histórico da credencial | Os envios do webhook daquela credencial. |
Nas duas telas, você pode pesquisar pelo código da venda ou pelo e-mail do cliente e filtrar por data e por evento.
Ao abrir um envio, a janela Detalhes do Log mostra:
| Detalhe | O que significa |
|---|---|
| Status | Situação do envio: pendente, enviando, enviado ou com erro. |
| Evento | Nome do evento. |
| URL | Para onde o aviso foi enviado. |
| Status Code | Status HTTP que o seu servidor respondeu. |
| Tentativa | Número da tentativa. |
| Sucesso | Se a entrega deu certo. |
| Erro | Mensagem de erro, quando houver. |
| Data | Quando o envio foi registrado. |
Reenviar um aviso
- Abra a tela Envios ou Logs do Webhook.
- Encontre o envio.
- No menu do envio, clique em Reenviar.
O reenvio monta o corpo com os dados atuais e usa a URL e o token que o webhook tem agora. A contagem de tentativas começa de novo.
Reenvio em massa
Use quando o seu servidor ficou fora do ar e perdeu vários avisos.
- Abra a tela Logs do Webhook do webhook.
- Clique em Reenvio em massa.
- Em A partir de, escolha a data e o horário do primeiro envio que você quer reenviar.
- Em Situação dos envios, escolha quais envios reenviar. Em branco, reenvia todos.
- Clique em Reenviar.
Reenviar tudo gera repetições
Se você reenviar também os envios que já tinham dado certo, o seu servidor recebe esses eventos de novo. Filtre pela situação com erro ou garanta que o seu servidor descarta repetidos. Veja Processar eventos sem duplicar.