Documentação Webhooks

Sumário

Introdução

O que são Webhooks
Visão geral do fluxo de eventos

Configuração

Como cadastrar seu endpoint
Pré-requisitos (HTTPS, autenticação, etc.)

Estrutura das Requisições

Propriedades do Payload Webhook
Exemplo de JSON de resposta
Resposta para o Comprovei

Troubleshooting

Por que não estou recebendo eventos?
Eventos duplicados
Endpoint lento ou indisponível
Reenvio manual de eventos

FAQ

Qual o timeout máximo do endpoint?
O que acontece se meu endpoint estiver fora do ar?
Existe limite de tamanho para o payload?
Posso receber webhooks em batch (vários eventos juntos) ou sempre é um por vez?
Como tratar eventos duplicados?
Existe ambiente de homologação/teste para webhooks?
O webhook garante ordem de entrega dos eventos?
Posso reprocessar um webhook antigo? Existe API pra isso?
Quais são os IPs/origens que preciso liberar no firewall?

Introdução

O que são Webhook

Nosso sistema de Webhooks permite que clientes configurem URLs de callback, que serão notificadas automaticamente sempre que eventos específicos ocorrerem na plataforma.

As notificações são enviadas por meio de requisições HTTP POST, no formato JSON, com suporte a autenticação através de Basic Auth ou Bearer Token.

Visão geral do fluxo de eventos

Como Funciona

1.O cliente cadastra uma ou mais URLs no painel de configuração de Webhooks.

2.Para cada evento relevante (ex: criação de rota, início de viagem, entrega realizada, etc.), o sistema verifica se há webhooks ativos para o tipo de evento.

3.O sistema envia uma requisição POST para cada URL registrada, com os dados do evento em formato JSON.

4.O cliente deve responder com status HTTP 2xx para confirmar o recebimento com sucesso. Caso contrário, tentaremos novamente (ver política de retries abaixo).

Configuração

Como cadastrar seu endpoint

Você pode acessar a tela de webhooks através do caminho Sistema > Webhooks .

Para cadastrar, vá em Webhooks > 3 pontinhos > adicionar

1	`Cadastro de Webhooks`

É necessário preencher os campos Nome, Descrição, URL e selecionar o tipo de autenticação. Observação: Somente será listado em autenticação as autenticações previamente cadastradas na aba Autenticações. **

Para adicionar um Header, basta clicar em Adicionar. Deve ser preenchido os campos Nome do campo e valor do campo. É possível inserir até 10 Headers.

É possível selecionar os tipos de eventos que você quer receber em seu endpoint relacionados a eventos de documento e eventos de rota. Para visualizar as os eventos disponível, basta expandir o tipo escolhido e selecionar os eventos que queira receber em seu endpoint

Eventos de Documento

Eventos de Rota

Para configurar Autenticações, basta ir na aba autenticações e em adicionar.

É obrigatório preencher os campos Nome, Descrição e Método de autenticação. Os campos adicionais variam conforme o método escolhido: Basic Authentication ou Bearer Token.

Autenticação

As chamadas podem usar Basic Authentication ou Bearer Token

Basic Auth

O cliente deverá informar um par de usuário e senha ao cadastrar a URL.

O header da requisição terá o seguinte formato:

Authorization: Basic

Exemplo:

Usuário: cliente123

Senha: minhaSenhaSecreta

Header: Authorization: Basic Y2xpZW50ZTEyMzptaW5oYVNlbnhhU2VjcmV0YQ==

Bearer

Deverá ser informado no cadastro do webhook um endpoint para obtenção do token

Este token será utilizado para autenticação no endpoint que será disparado pelo webhook

Estrutura das Requisições

Propriedades do Payload Webhook

Documento

Campo	Descrição
UUIDDocumento	Hash identificador único daquele documento
Chave	Chave única de 44 dígitos
Tipo	Tipo do documento (NFe, MDFe, CTe, etc)
Modelo	Modelo do documento (Ex: 55 = NFe)
Numero	Número do documento
Serie	Série do documento
CodCliente	CNPJ para clientes brasileiros
CodInternoCliente	Código do cliente final, fornecido pelo cliente Comprovei
LinkRastreamento	URL para rastreio da entrega
CodStatusDocumento	Código do status daquele documento (Listagem completa aqui)
DescStatusDocumento	Nome do status daquele documento
PedidosAssociados
-PedidoInterno
-PedidoCliente
-DataPedido	Lista de pedidos associados àquele documento

Rota

Campo	Descrição
UUIDRota	Hash identificador único daquela rota
Data	Data da rota (pode não ser a mesma data da execução)
Nome	Nome identificador da rota
Numero	Número da rota
CodMotorista	Username do motorista (geralmente é o CPF)
CpfMotorista	CPF do Motorista
Placa	Placa do veículo associado à rota
Tipo	D (Distribuição), T (Transbordo), P (Praça), R (Retorno)
Regiao	Região associada àquela rota
CNPJTransportador	CNPJ do transportador associado àquela rota
UUIDEvento	Hash identificador único daquele evento exportado
DataHoraEvento	Data e Hora da execução daquele evento
DataHoraSincronizacao	Data e Hora da sincronização daquele evento
OrigemEvento	Aplicativo Motorista Comprovei, Aplicativo de terceiros,
Apontamento manual pelo Console comprovei, Outro
CodEventoComprovei	Código único do evento dentro do Comprovei
NomeEventoComprovei	Nome do evento dentro do Comprovei
DescEventoComprovei	Descrição do evento dentro do Comprovei
CodEventoNstech	Código do evento na Plataforma da NSTech (descontinuado)
DescEventoNstech	Descrição do evento na Plataforma da NSTech (descontinuado)
CodEventoSistema3o	Código do evento enviado por sistema terceiro
DescEventoSistema3o	Descrição do evento enviado por sistema terceiro
Comprovacoes	Lista de eventos: Anexo 2
CodUsuario	Geralmente será o CPF, mas pode não ser. Importante: o
motorista da rota pode ser um, mas quem faz o apontamento no lugar
dele é outro. Por isso, que o usuário aparece aqui em Comprovações e
no grupo Rota
CpfUsuario	CPF do usuário, cadastrado no campo CPF, diferente do item anterior que é o username
ModeloDispositivo	Modelo do aparelho celular do usuário que registrou o evento (motorista)
IdDispositivo	Id interno Android do usuário que registrou o evento (motorista)
Coordenadas
-Latitude
-Longitude	Geolocalização coletada no momento daquele evento
Fotos
Foto
Comentario	Comentário feito pelo motorista na imagem
LinkFoto	URL para acessar a foto da comprovação
Smartscans
Smartscan
Comentário	Comentário feito pelo motorista na imagem
LinkSmartscan	URL para acessar a foto da comprovação
Assinatura
Nome	Nome da pessoa que assinou
LinkAssinatura	URL para acessar a imagem da assinatura
Comentario
Texto	Texto do comentário na comprovação tipo ‘anotação’
ConferenciaItens
CodItem	Código do item (geralmente SKU)
Descricao	Descrição do item
CodBarras	Código de barras do item
QuantidadePrevista	Quantidade prevista a ser entregue/coletada daquele item
QuantidadeConferida	Quantidade conferida(bipada) daquele item
QualidadeProcedimentoMotorista
IndiceQualidadeCalculada	Valor numérico da qualidade calculada
Criterios
Criterio
Nome	Critério que foi avaliado para a qualidade
PesoMediaPonderada	Peso daquele critério para o cálculo da média
CriterioAtendido	Se aquele critério foi atendido (Sim/Não)

ETA

Campo	Descrição
CodStatusETA	Descontinuado (ignorar)
DescStatusETA	Descontinuado (ignorar)
ETAOriginal	Data e Hora do ETA calculado inicialmente
ETARecalculado	Data e Hora do ETA recalculado
JanelaDestinatario
DataHoraInicio	Data e Hora do início da janela de entrega
DataHoraFim	Data e Hora do fim da janela de entrega

SLA

Campo	Descrição
DataHoraSLAOriginal	Data e Hora do SLA original
DataHoraSLAAjustado	Data e Hora do SLA ajustado
StatusSLA	No prazo, Previsto - Atraso, Finalizado - No
prazo, Finalizado - Atraso], versão inicial virá sempre com cod e
descrição

Exemplo de JSON de resposta:

{
   "specVersion":"1.0",
   "type":"com.comprovei.EventoDocumento",
   "source":"Comprovei",
   "id":"b08a68121fa427dbb5e7876d5c4d797df70f744a53ea22e3698c5175ee323296",
   "time":"2022-11-03T15:19:49-03:00",
   "dataContentType":"application/json",
   "data":{
      "Rota":{
         "UUIDRota":"dc4eda751cb97602de952d6bd30c7b7fbfa832dd91bb2d0682e424f282f9c879",
         "Data":"2025-04-03",
         "Nome":null,
         "Numero":"Transbordo #123",
         "CodMotorista":"0015",
         "Placa":"ABC4321",
         "Tipo":"Transbordo",
         "Regiao":"",
         "CNPJTransportador":"33902814000170",
         "EmissaoCarbono":false
      },
      "Documento":{
         "UUIDDocumento":"60bd686a99237d88acfe380da348204de2772381f557908250f70388b8fb9753",
         "Chave":"35190412345678000123550010000012341000012345",
         "Tipo":"NFE",
         "Modelo":0001,
         "Numero":"000001234",
         "Serie":"0",
         "CodCliente":"13373113000184",
         "CodInternoCliente":"E01569",
         "LinkRastreamento":"",
         "CodStatusDocumento":"17",
         "DescStatusDocumento":"Transferido",
         "PedidosAssociados":[
            {
               "PedidoInterno":null,
               "PedidoCliente":"281044455",
               "DataPedido":"2022-11-03"
            }
         ]
      },
      "Comprovacoes":{
         "CodUsuario":"0015",
         "ModeloDispositivo":"707ee863aae11d06",
         "IdDispositivo":"SM-A115M""Coordenadas":{
            "Latitude":"-22.4245672",
            "Longitude":"-45.4492451"
         },
         "Fotos":[

         ],
         "SmartScans":[

         ],
         "ConferenciaItens":[
            {
               "CodItem":"0467911064000017",
               "Descricao":"Volume 00001/00001",
               "CodBarras":"0467911064000017",
               "QuantidadePrevista":"1",
               "QuantidadeConferida":"0"
            }
         ]
      },
      "QualidadeProcedimentoMotorista ":{
         "IndiceQualidadeCalculada":"0.00",
         "Criterios":"Criterio":[
            {
               "Nome":"INICIO_VIAGEM_DENTRO_CERCA_VIAGEM_ANTERIOR",
               "PesoMediaPonderada":"1",
               "CriterioAtendido":"Não"
            },
            {
               "Nome":"CHEGADA_NA_CERCA_LOCAL_ENTREGA",
               "PesoMediaPonderada":"0",
               "CriterioAtendido":"Não"
            },
            {
               "Nome":"FINALIZOU_COM_APONTAMENTOS",
               "PesoMediaPonderada":"0",
               "CriterioAtendido":"Não"
            },
            {
               "Nome":"TEMPO_ENTRE_MARCAR_CHEGADA_E_FINAL_MAIOR_QUE_O_MINIMO",
               "PesoMediaPonderada":"1",
               "CriterioAtendido":"Não"
            }
         ]
      }
   },
   "ETA":{
      "CodStatusETA":"",
      "DescStatusETA":"",
      "ETAOriginal":"2022-11-04T16:04:15-03:00",
      "ETARecalculado":"2022-11-04T16:04:15-03:00",
      "JanelaDestinatario":{
         "DataHoraInicio":"",
         "DataHoraFim":""
      }
   },
   "SLA":{
      "DataHoraSLAOriginal":"2022-07-12T11:39:45-03:00",
      "DataHoraSLAAjustado":"",
      "StatusSLA":""
   },
   "UUIDEvento":"b08a68121fa427dbb5e7876d5c4d797df70f744a53ea22e3698c5175ee323296",
   "DataHoraEvento":"2022-11-03T14:44:34-03:00",
   "DataHoraSincronizacao":"2022-11-03T15:19:47-03:00",
   "OrigemEvento":"Aplicativo Motorista Comprovei",
   "CodEventoComprovei":null,
   "DescEventoComprovei":"Arrival at Base",
   "CodEventoNstech":"1.01.99",
   "DescEventoNstech":"Inicio/Fim de Transporte - Fim de Viagem",
   "CodEventoSistema3o":"",
   "DescEventoSistema3o":""
}
}

Resposta para o Comprovei

Em caso de sucesso da requisição, o endpoint acionado pelo webhook deverá responder com status HTTP 200 e uma mensagem no seguinte formato:

{

"status": 200

"message": "(qualquer string que queira retornar para o Comprovei)" 

}

Assim o sistema da Comprovei entenderá que a mensagem foi recebida com sucesso e não há necessidade de reenvio.

Em caso de erro, enviar o código HTTP com a respectiva mensagem

Deverá ser enviado o código de status no corpo da mensagem e no código HTTP

Eventos disponíveis

Nossa plataforma disponibiliza dois tipos de eventos: Eventos de Documentos e Eventos de Rotas. Abaixo, você encontra um exemplo de cada estrutura para melhor compreensão.

Em Eventos de Documentos, temos as possibilidades:

Documento criado/importado, Documento adicionado em rota, Viagem iniciada, Chegada no cliente, Itens conferidos/escaneados, Entrega realizada, Viagem abortada, Viagem pausada, Viagem retomada, Entrega agendada/programada, Prazo SLA alterado, Prazo de entrega alterado, Entrega não realizada, Devolução, Documento cancelado, Documento editado e Documento excluído.

Exemplo de Json relacionada a Evento de Documento

{
   "specVersion":"1.0",
   "type":"com.comprovei.EventoDocumento",
   "source":"Comprovei",
   "id":"8a7934799c3e40c6e2cb960963e298753051288524a6003f529aa728c760fd40",
   "time":"2025-08-20T14:31:19-03:00",
   "dataContentType":"application/json",
   "data":{
      "Rota":{
         "UUIDRota":"27002046a838fe0db7dd4cd7b4a25f0c8ae8bca655a8bc61d1512a7dcc3f9c81",
         "Data":"2025-08-20",
         "Nome":"934212",
         "Numero":"13903699",
         "CodMotorista":"02862493406",
         "CpfMotorista":"02862493406",
         "Placa":"BBP7C14",
         "Tipo":"Distribuição",
         "Regiao":"119-FV SÃO JOSE DO MIBIPU",
         "CNPJTransportador":"14578966000115"
      },
      "Documento":{
         "UUIDDocumento":"9927709435a36e8de1bdfc81b9dbe87f317c88c67582c8ad704d780bf4a80ee2",
         "Chave":"24250883310441009173550010003771581252677686",
         "Tipo":"NFe",
         "Modelo":"",
         "Numero":"377158",
         "Serie":"1",
         "CodCliente":"10700961000405",
         "CodInternoCliente":"",
         "LinkRastreamento":"https://tracking.comprovei.com/#/track/UrbPoRGQ41zfnPLZlEi6SlWRPZZk+bn+",
         "CodStatusDocumento":"4",
         "DescStatusDocumento":"Entregue",
         "PedidosAssociados":[
            {
               "PedidoInterno":"24679536",
               "PedidoCliente":"69485516",
               "DataPedido":"2025-08-20"
            }
         ]
      },
      "Comprovacoes":{
         "CodUsuario":"02862493406",
         "CpfUsuario":"02862493406",
         "ModeloDispositivo":"SM-A055M",
         "IdDispositivo":"c6e2e672015fe4cb",
         "Coordenadas":{
            "Latitude":"-6.0365681",
            "Longitude":"-37.0211558"
         },
         "Fotos":[
            {
               "Comentario":null,
               "LinkFoto":"http://images.comprovei.com.br/0U63381V7wyWjykirqEfDQlVUeljZ+PftMFmI4Y1+QHdnq8osSjBA3YP/2UTCDHT/k6NVbx//kVawwmxA1dl0wslTv6AdrK+kgz5tRyn3vc+9WgAOxCRF54="
            }
         ],
         "SmartScans":[

         ],
         "ConferenciaItens":[
            {
               "CodItem":"979796978",
               "Descricao":"HAMBURGUER DE CARNE BOVINA - AURORA - SABOR P",
               "CodBarras":"2121",
               "QuantidadePrevista":"32",
               "QuantidadeConferida":"0"
            },
            {
               "CodItem":"979796979",
               "Descricao":"PAO DE ALHO - AURORA",
               "CodBarras":"2676",
               "QuantidadePrevista":"7",
               "QuantidadeConferida":"0"
            }
         ]
      },
      "QualidadeProcedimentoMotorista ":{
         "IndiceQualidadeCalculada":"0.00",
         "Criterios":{
            "Criterio":[
               {
                  "Nome":"INICIO_VIAGEM_DENTRO_CERCA_VIAGEM_ANTERIOR",
                  "PesoMediaPonderada":0,
                  "CriterioAtendido":"Não"
               },
               {
                  "Nome":"CHEGADA_NA_CERCA_LOCAL_ENTREGA",
                  "PesoMediaPonderada":0,
                  "CriterioAtendido":"Não"
               },
               {
                  "Nome":"FINALIZOU_COM_APONTAMENTOS",
                  "PesoMediaPonderada":0,
                  "CriterioAtendido":"Não"
               },
               {
                  "Nome":"TEMPO_ENTRE_MARCAR_CHEGADA_E_FINAL_MAIOR_QUE_O_MINIMO",
                  "PesoMediaPonderada":0,
                  "CriterioAtendido":"Não"
               }
            ]
         }
      },
      "ETA":{
         "CodStatusETA":"",
         "DescStatusETA":"",
         "ETAOriginal":"2025-08-20T11:20:00-03:00",
         "ETARecalculado":"2025-08-20T11:20:00-03:00",
         "JanelaDestinatario":{
            "DataHoraInicio":"",
            "DataHoraFim":""
         }
      },
      "SLA":{
         "DataHoraSLAOriginal":"",
         "DataHoraSLAAjustado":"",
         "StatusSLA":""
      },
      "UUIDEvento":"8a7934799c3e40c6e2cb960963e298753051288524a6003f529aa728c760fd40",
      "DataHoraEvento":"2025-08-20T14:24:27-03:00",
      "DataHoraSincronizacao":"2025-08-20T14:31:19-03:00",
      "OrigemEvento":"Aplicativo Motorista Comprovei",
      "CodEventoComprovei":"000",
      "NomeEventoComprovei":"Entrega normal",
      "DescEventoComprovei":"Entrega realizada normalmente",
      "CodEventoNstech":"1.22.01",
      "DescEventoNstech":"Entrega/Coleta Realizada - Sem Restrições",
      "CodEventoSistema3o":"",
      "DescEventoSistema3o":""
   }
}

Em Eventos de Rotas, temos as possibilidades:

Rota criada/importada, Rota iniciada, Viagem de retorno iniciada, Viagem de retorno pausada, Rota finalizada, Rota editada e Rota excluída.

Exemplo de Json relacionada a Evento de Rota

{
   "specVersion":"1.0",
   "type":"com.comprovei.EventoRota",
   "source":"Comprovei",
   "id":"dff0f34ba5efdc0f5cdb1c855fd9b4c173ad694f1528c2796410e2fac3cc7fbe",
   "time":"2025-07-11T15:08:14-03:00",
   "dataContentType":"application/json",
   "data":{
      "Rota":{
         "UUIDRota":"f6c768c3d19cb8e9a5c962795cf3a9f1197a2bcfca6f1d45b4c141e69cdafbc1",
         "Data":"2025-07-11",
         "Nome":"",
         "Numero":"Rota 1 | a31e",
         "CodMotorista":"moura.brasil10",
         "CpfMotorista":"",
         "Placa":"LLP8790",
         "Tipo":"Distribuição",
         "Regiao":"",
         "CNPJTransportador":"12345678910123"
      },
      "Comprovacoes":{
         "CodUsuario":"moura.brasil10",
         "CpfUsuario":"",
         "ModeloDispositivo":"SM-M146B",
         "IdDispositivo":"19182e00abe20376",
         "Coordenadas":{
            "Latitude":"-22.4222531",
            "Longitude":"-45.4601146"
         },
         "Fotos":[

         ],
         "SmartScans":[

         ],
         "ConferenciaItens":[

         ]
      },
      "UUIDEvento":"dff0f34ba5efdc0f5cdb1c855fd9b4c173ad694f1528c2796410e2fac3cc7fbe",
      "DataHoraEvento":"2025-07-11T15:08:14-03:00",
      "DataHoraSincronizacao":"",
      "OrigemEvento":"Aplicativo Motorista Comprovei",
      "CodEventoComprovei":"route_started",
      "NomeEventoComprovei":"Route Started",
      "DescEventoComprovei":"Inicio/Fim de Transporte - Inicio de Viagem",
      "CodEventoNstech":"1.01.01",
      "DescEventoNstech":"Inicio/Fim de Transporte - Inicio de Viagem",
      "CodEventoSistema3o":"",
      "DescEventoSistema3o":""
   }
}

Retentativa de Entregas

Esse recurso ainda não está disponível, mas já está em nossa lista de prioridades para desenvolvimento

Boas Práticas para Integração com Webhooks

Para garantir que os webhooks sejam entregues corretamente e processados com sucesso pelo seu sistema, recomendamos seguir as práticas abaixo:

1. Alta Disponibilidade da URL

Certifique-se de que a URL configurada esteja sempre disponível (24/7), especialmente se for crítica para processos internos.
Use infraestrutura confiável (como cloud providers com SLA elevado) e, se possível, balanceadores de carga e redundância.
Evite quedas prolongadas ou bloqueios por firewall.

2. Tempo de Resposta Rápido

Mantenha o tempo de resposta da URL inferior a 2 segundos sempre que possível. •Se o processamento for demorado, responda 200 OK imediatamente e processe os dados de forma assíncrona.

3. Validação de Segurança

Verifique o header de autenticação Basic Auth para garantir que a chamada seja legítima. •Opcionalmente, valide o IP de origem ou implemente tokens/HMAC para reforço da segurança (entre em contato para configurar isso).

4. Trate Todas as Requisições com Idempotência

Seu endpoint deve ser capaz de lidar com reenvios do mesmo evento sem causar efeitos colaterais (como criar pedidos duplicados).
Utilize os campos UUID como referência para detectar duplicidade.

5. Monitore e Logue os Webhooks

Mantenha logs detalhados de todas as requisições recebidas, incluindo horário, payload, status HTTP e tempo de resposta.
Configure alertas para falhas recorrentes ou lentidão excessiva.

6. Utilize HTTPS

Sempre forneça URLs com protocolo seguro () para proteger os dados em trânsito. •Certifique-se de que o certificado SSL esteja válido e atualizado.

https://

7. Gerencie Erros com Clareza

Em caso de falha no seu sistema, retorne códigos HTTP adequados (ex: 500, 503, 401) e mensagens claras para facilitar o diagnóstico.
Não retorne 200 OK se o processamento falhou.

8. Evite Rate Limiting Agressivo

Permita que nosso sistema envie múltiplos eventos em sequência sem bloqueio por limite de requisições (rate limit).
Se aplicar limites, informe nossa equipe para ajustarmos a taxa de envio.

9. Ambiente de Homologação

Para projetos novos ou mudanças em produção, recomendamos configurar uma URL de testes/homologação para validação prévia dos webhooks.

10. Tenha um Plano de Contingência

Implemente filas internas e sistemas de retry no seu lado, caso sua API dependa de sistemas externos.
Garanta que falhas temporárias não impeçam o consumo adequado dos eventos.

Troubleshooting

Por que não estou recebendo eventos?

Se você não está recebendo eventos, os motivos mais comuns são:

Endpoint incorreto: Verifique se a URL do seu endpoint de webhook está configurada corretamente na plataforma. Qualquer erro de digitação, como um .com faltando ou uma / extra, pode impedir a entrega.
Problemas de conectividade: Certifique-se de que seu servidor esteja online e acessível publicamente na internet. Firewalls ou configurações de rede podem estar bloqueando as requisições que chegam da nossa plataforma.
Eventos não inscritos: Confirme se você se inscreveu para os tipos de eventos corretos. Se, por exemplo, você quer receber eventos de "pedido criado", mas só se inscreveu para "pagamento aprovado", não receberá o evento esperado.
Códigos de status HTTP: Se o seu endpoint retornar códigos de erro HTTP (como 4xx ou 5xx), nossa plataforma pode parar de tentar enviar o evento, assumindo que há um problema do seu lado.

Eventos duplicados

Em alguns cenários, você pode receber o mesmo evento mais de uma vez. Isso geralmente ocorre devido a falhas de comunicação ou timeouts durante o envio. Para lidar com essa situação, a melhor prática é tornar seu sistema idempotente.

O que é idempotência? É a capacidade de uma operação produzir o mesmo resultado, independentemente de quantas vezes ela seja executada. Para garantir isso, use o ID único do evento (ou algum outro identificador único, como o ID de um pedido) para verificar se o evento já foi processado.

Exemplo: Antes de processar um evento, verifique se o ID do evento já existe no seu banco de dados. Se sim, ignore-o. Se não, processe e salve o ID para futuras verificações.

Endpoint lento ou indisponível

Se o seu endpoint de webhook estiver lento para responder ou estiver fora do ar, nossa plataforma adotará uma estratégia de retentativas com backoff exponencial para garantir a entrega.

Retentativas: Tentaremos enviar o evento novamente em intervalos de tempo que aumentam gradualmente.
Backoff exponencial: A cada falha, o tempo de espera antes da próxima tentativa aumenta. Por exemplo: 1 minuto, 5 minutos, 30 minutos, etc., até um limite máximo de tentativas ou um período total de tempo.

Melhor prática: Para evitar que seu endpoint seja considerado indisponível, responda a requisição de webhook o mais rápido possível (com um 200 OK) e processe a lógica do evento de forma assíncrona.

Reenvio manual de eventos

Caso você precise reprocessar um evento que falhou ou não foi recebido, será necessário abrir um chamado com nosso time de Suporte. Posteriormente, teremos a opção de reenvio manual na tela de webhooks.

FAQ

Perguntas frequentes

Existe ambiente de homologação? Não

Qual o timeout máximo do endpoint?

Nossa plataforma não define um tempo limite (timeout) rígido para o seu endpoint. Isso significa que continuaremos tentando enviar o webhook por um período estendido.

No entanto, é crucial que o seu servidor responda a nossa requisição o mais rápido possível. Se a sua aplicação demorar para processar o webhook, a conexão pode ser encerrada pelo nosso sistema, resultando em falhas na entrega.

O que acontece se meu endpoint estiver fora do ar? Webhook marca a mensagem de erro e status retornado

Existe limite de tamanho para o payload? Não

Posso receber webhooks em batch (vários eventos juntos) ou sempre é um por vez? Teoricamente sim, mas no momento enviamos 1 por 1. Organize seu endpoint para que possa receber um array.

Como tratar eventos duplicados? Todo evento tem um id associado. Fica a critério de quem consome.

O webhook garante ordem de entrega dos eventos? Não. Tentamos enviar na ordem, mas sem garantia.

Posso reprocessar um webhook antigo? Existe API pra isso? Hoje não. Vai ter no futuro pela tela de webhooks mesmo.