O que um endpoint de webhook de rastreamento deve retornar? Códigos de status, tempos limite e novas tentativas?
A URL de endpoint de um webhook de rastreamento deve retornar uma resposta 2xx rápida e intencional depois de aceitar o evento para processamento. Na maioria das integrações, o padrão mais seguro é autenticar a solicitação, validar o payload, armazenar ou enfileirar o evento e confirmá-lo com 200 OK ou 202 Accepted. Use respostas 4xx para solicitações que o remetente não deve tentar novamente e respostas 5xx quando um problema temporário no lado do servidor impedir a aceitação. O comportamento exato de timeout e novas tentativas ainda depende do contrato do provedor do webhook, portanto, sua implementação deve ser projetada com base no comportamento documentado do remetente, e não em suposições.

Para um webhook de rastreamento ou de status de remessa, essa distinção é importante porque os eventos de entrega podem chegar mais de uma vez, fora de ordem ou ser reproduzidos após uma falha de rede. A função do endpoint não é necessariamente concluir todas as operações comerciais antes de responder. Sua primeira função é tomar uma decisão confiável sobre aceitar ou não o evento.
O contrato de resposta em termos práticos
Uma resposta de webhook tem dois públicos: o sistema remetente e sua própria aplicação. O remetente precisa de um resultado HTTP claro para decidir se deve marcar a entrega como bem-sucedida, tentar novamente ou parar. Sua aplicação precisa de tempo suficiente para verificar e registrar o evento de forma durável. Esses objetivos são mais fáceis de alcançar quando o endpoint tem um pequeno caminho síncrono e um caminho separado de processamento assíncrono.
- Receba a solicitação HTTP por HTTPS.
- Verifique a assinatura, as credenciais de autenticação, o timestamp ou outros controles de integridade da solicitação exigidos pelo provedor.
- Analise e valide o payload sem executar operações lentas em sistemas downstream.
- Grave o evento, ou um registro de deduplicação e uma referência do evento, em um armazenamento durável ou em uma fila confiável.
- Retorne uma resposta 2xx intencional.
- Processe de forma assíncrona a atualização do rastreamento, a notificação ao cliente, a alteração de inventário ou outra ação comercial.
Uma resposta não deve afirmar que houve aceitação se o evento existir apenas na memória do processo. Se a aplicação falhar imediatamente após retornar sucesso, um evento que nunca foi persistido poderá ser perdido enquanto o remetente acredita que a entrega foi bem-sucedida. Portanto, o momento em que você retorna 2xx deve corresponder à sua garantia real de durabilidade.
Qual código de status um webhook deve retornar?
| Resposta | Significado para o remetente | Uso típico em webhooks |
|---|---|---|
200 OK | A solicitação foi aceita e tratada com sucesso. | Um padrão prático após a validação e a aceitação durável. |
202 Accepted | A solicitação foi aceita para processamento, mas o trabalho pode continuar. | Útil quando o evento foi colocado com segurança em uma fila, mas o processamento comercial é assíncrono. |
204 No Content | A solicitação foi bem-sucedida e nenhum corpo de resposta é necessário. | Adequado quando o provedor aceita uma resposta de sucesso vazia. |
400–499 | A solicitação é inválida, não autorizada ou não aceitável conforme enviada. | Payload malformado, falha de autenticação, assinatura inválida ou evento rejeitado permanentemente. |
429 Too Many Requests | O receptor está aplicando limitação de taxa. | Use somente quando o comportamento de novas tentativas do remetente e sua política de limitação de taxa forem compatíveis. |
500–599 | O receptor não pôde aceitar a solicitação devido a um problema no servidor ou temporário. | Indisponibilidade do banco de dados, falha da fila, falha de dependência ou erro inesperado da aplicação. |
200 OK costuma ser a escolha menos surpreendente porque é amplamente entendido como recebimento bem-sucedido. 202 Accepted também é semanticamente útil quando o endpoint aceitou o evento para processamento posterior. Nenhum dos dois códigos é automaticamente correto: a documentação do remetente pode definir quais respostas 2xx contam como bem-sucedidas, e alguns provedores podem esperar um corpo ou tipo de conteúdo específico.
Não retorne uma resposta 2xx apenas porque a solicitação HTTP chegou ao seu servidor. Se a verificação da assinatura falhar ou o payload não puder ser interpretado com segurança, uma resposta 4xx geralmente é mais honesta. Por outro lado, não retorne 4xx para uma indisponibilidade temporária do banco de dados se o evento puder ser processado posteriormente. Uma resposta 5xx dá ao remetente, quando compatível com novas tentativas, a chance de entregar o evento novamente, embora o provedor possa aplicar sua própria política.
Como os timeouts devem ser tratados?
Os valores de timeout de webhooks são específicos de cada provedor. Não existe um timeout HTTP universal usado por todas as plataformas de rastreamento, e um remetente pode parar de esperar antes que sua aplicação conclua uma operação lenta. Trate o timeout documentado pelo remetente como um limite máximo, não como uma meta. Normalmente, seu endpoint deve responder bem antes desse limite.
O erro de design mais comum é executar todo o trabalho downstream antes de confirmar o webhook. Um manipulador pode chamar um banco de dados, um sistema de gerenciamento de pedidos, um serviço de notificações e um pipeline de análise em sequência. Uma dependência lenta pode fazer o remetente detectar um timeout mesmo que sua aplicação eventualmente conclua o trabalho. O remetente poderá então tentar novamente, criando processamento duplicado ou atualizações concorrentes.
Mantenha o caminho síncrono limitado ao trabalho necessário para tomar uma decisão segura de aceitação. Isso geralmente inclui autenticação da solicitação, validação básica do esquema, armazenamento durável do evento e publicação na fila. Coloque enriquecimentos dispendiosos, consultas a transportadoras, mensagens aos clientes e chamadas de APIs de terceiros atrás de um worker. Monitore separadamente o tempo gasto recebendo, validando, persistindo e confirmando o evento e o tempo gasto processando-o.
Um timeout não é o mesmo que uma operação comercial malsucedida. Do ponto de vista do remetente, um timeout geralmente significa que ele não recebeu uma resposta de sucesso utilizável. Seu serviço pode ter armazenado o evento com sucesso pouco antes de a conexão ser encerrada. É por isso que idempotência e deduplicação são necessárias mesmo quando o endpoint parece confiável.
O que causa novas tentativas?
Um remetente de webhook pode tentar novamente após um erro de conexão, um timeout ou uma resposta que seu contrato classifique como malsucedida. O cronograma exato, o número máximo de tentativas, o algoritmo de espera progressiva e a janela de entrega variam conforme o provedor. Não prometa um número fixo de tentativas, a menos que isso esteja declarado na documentação do provedor.
O receptor deve presumir que novas tentativas podem ocorrer e projetar o sistema deliberadamente para isso:
- Use um identificador de evento quando disponível. Armazene-o com uma restrição de unicidade ou uma chave de deduplicação equivalente.
- Torne o processamento idempotente. Aplicar duas vezes a mesma atualização de status da entrega não deve enviar duas mensagens ao cliente, criar dois reembolsos nem avançar um pedido incorretamente.
- Mantenha o payload original ou um registro de auditoria útil. Isso permite reprodução, investigação e reconciliação.
- Separe aceitação de processamento. Um worker pode tentar novamente as falhas internas sem forçar o remetente a repetir toda a troca HTTP.
- Registre os códigos de resposta e a latência. Um aumento nas respostas 5xx, nos timeouts ou nos IDs de eventos duplicados pode revelar uma indisponibilidade antes que os usuários relatem atualizações de rastreamento ausentes.
Um evento duplicado geralmente deve receber uma resposta de sucesso se o evento original já tiver sido aceito de forma durável. Retornar um erro para cada duplicata pode desencadear novas tentativas desnecessárias. O endpoint pode registrar que o evento já foi visto, ignorar a ação comercial repetida e retornar a mesma classe de sucesso usada para um evento recém-aceito.
Quando retornar 4xx, 429 ou 5xx?
Retorne 4xx quando seja improvável que tentar novamente a mesma solicitação resolva o problema. Exemplos incluem uma assinatura inválida, autenticação obrigatória ausente, formato de payload não compatível ou uma solicitação que viole uma regra de validação permanente. Antes de escolher 4xx, verifique se o remetente trata esse status como uma falha permanente. Algumas plataformas têm suas próprias regras para entregas malsucedidas.
Use 429 com cuidado. O HTTP define 429 para limitação de taxa, e o cabeçalho Retry-After pode comunicar quando uma nova tentativa pode ser apropriada. No entanto, nem todo remetente de webhook interpreta 429 da mesma maneira. Se sua fila estiver cheia ou seu serviço sobrecarregado, confirme que o provedor tentará novamente com segurança e que seu cronograma de tentativas não agravará a sobrecarga. Uma fila de entrada limitada e um plano de contrapressão geralmente são melhores do que permitir que as solicitações falhem de forma imprevisível.
Retorne 5xx quando o receptor não puder aceitar o evento com segurança devido a um problema temporário. Isso inclui um banco de dados indisponível, uma falha na gravação em uma fila durável ou um erro interno que tenha impedido a validação ou a persistência. Retornar 200 enquanto descarta silenciosamente o evento dificulta a recuperação, pois o remetente não terá motivo para tentar novamente.
Evite depender de redirecionamentos como 301, 302 ou 307 para a entrega de webhooks. O tratamento de redirecionamentos varia entre os clientes, e redirecionar uma solicitação assinada pode gerar ambiguidade em relação ao destino, ao método e ao corpo. Configure o provedor com o endpoint HTTPS final.
Uma política de resposta confiável para eventos de rastreamento
Para a maioria das integrações de webhooks de rastreamento, a política a seguir é um ponto de partida sensato:
- Retorne
200ou202depois que o evento passar pela autenticação e tiver sido armazenado de forma durável ou colocado em uma fila confiável. - Retorne uma resposta 4xx para uma assinatura inválida, autenticação inválida ou payload permanentemente inutilizável, seguindo as regras documentadas pelo provedor.
- Retorne 5xx quando uma falha temporária impedir a aceitação durável.
- Retorne uma resposta de sucesso para uma duplicata reconhecida com segurança, impedindo efeitos comerciais duplicados.
- Mantenha o manipulador rápido e meça sua latência de confirmação.
- Teste cenários de timeout, novas tentativas, duplicação, eventos fora de ordem, dados malformados e indisponibilidade do provedor antes do lançamento em produção.
Se você estiver integrando uma API de rastreamento, comece pela documentação de webhook do provedor e confirme os códigos de sucesso aceitos, o método de assinatura da solicitação, o timeout, os gatilhos de novas tentativas, o esquema do payload e o identificador do evento. Para integrações com a 17TRACK, a documentação oficial da Tracking API é o local apropriado para verificar o contrato específico do provedor, em vez de inferi-lo a partir da prática geral de HTTP.
Lista de verificação da implementação
- O endpoint pode ser acessado por HTTPS e tem uma URL de produção estável.
- A autenticação e a verificação da assinatura ocorrem antes do processamento comercial.
- A solicitação bruta ou uma representação verificável é retida quando necessário para verificações de assinatura e solução de problemas.
- O evento é persistido antes do envio da resposta de sucesso.
- Entregas duplicadas são seguras e não repetem ações irreversíveis.
- Os workers podem tentar novamente o processamento interno independentemente do ciclo de novas tentativas HTTP do remetente.
- Os logs incluem ID do evento, horário de entrega, código de resposta, estado do processamento e ID de correlação sem expor segredos.
- Os alertas distinguem timeouts do endpoint, falhas de validação 4xx, indisponibilidades 5xx, atrasos na fila e entregas duplicadas.
- O comportamento documentado do provedor foi testado com eventos reais ou de sandbox.
FAQ
200 OK é melhor que 202 Accepted para um webhook?
Nenhum dos dois é universalmente melhor. Use 200 OK quando a solicitação tiver sido aceita e sua integração tratar a resposta como um sucesso geral. Use 202 Accepted quando o evento tiver sido aceito para processamento assíncrono. Confirme se o remetente classifica a resposta 2xx escolhida como bem-sucedida.
Um endpoint de webhook deve esperar até que a atualização do rastreamento seja totalmente processada?
Geralmente, não. Ele deve esperar apenas até que o evento seja autenticado, validado e aceito de forma durável. O trabalho de longa duração normalmente deve ocorrer após a confirmação, para que uma dependência lenta não cause um timeout e uma nova tentativa evitáveis.
O que deve acontecer quando o mesmo evento de rastreamento chega duas vezes?
Reconheça-o usando o ID do evento do provedor ou uma chave equivalente cuidadosamente projetada, ignore os efeitos colaterais duplicados e retorne uma resposta de sucesso se o evento já tiver sido aceito. Isso torna as novas tentativas seguras sem ocultar novas falhas de processamento.
Uma assinatura inválida deve retornar 400 ou 401?
A escolha depende do seu modelo de autenticação e das expectativas documentadas pelo provedor. Ambos podem comunicar rejeição, mas a consistência é mais importante do que escolher um deles universalmente. Não confirme um evento cuja autenticidade você não possa verificar.
Uma resposta 5xx sempre causa uma nova tentativa?
Não. Muitos sistemas de webhook tentam novamente em caso de timeouts e erros do servidor, mas os gatilhos e cronogramas de novas tentativas são específicos de cada provedor. Trate as novas tentativas como um comportamento documentado da integração e verifique-o em um ambiente de teste.
Fontes
- RFC 9110: Semântica HTTP — definições para sucesso, erro do cliente, erro do servidor, redirecionamento e tratamento de respostas.
- RFC 6585: Códigos de status HTTP adicionais — especificação para
429 Too Many Requests. - Documentação de Webhooks da Stripe — orientações práticas sobre respostas de webhooks, processamento assíncrono e tratamento de eventos duplicados.
- Documentação do GitHub: Como tratar entregas de webhooks — inspeção de entregas e considerações operacionais para integrações de webhooks.
- Documentação da Tracking API da 17TRACK — documentação específica do provedor a ser consultada ao implementar integrações com a Tracking API.


