Retry de webhook da Shopify, medido: 9 tentativas em 4 horas e depois nada

A Shopify tenta entregar um webhook com falha 9 vezes: a primeira tentativa mais 8 novas tentativas (retries), a última 4 horas depois do evento. Depois disso, ela para. No nosso teste, não enviou mais nada desses pedidos, nem quando o servidor voltou. Os pedidos existem na Shopify, e seu sistema nunca fica sabendo deles pelo webhook.

A documentação da Shopify informa o total, 8 novas tentativas em 4 horas, mas não quando cada tentativa acontece. Então medimos. Fizemos quatro pedidos de teste numa loja de desenvolvimento da Shopify, fizemos o receptor responder 503 por pouco menos de seis horas e registramos cada requisição.

TL;DR

• As tentativas chegaram em cerca de 2 s, 3 s, 1 min, 3 min, 8 min, 30 min, 1 h, 2 h e 4 h. Os quatro pedidos seguiram esse cronograma com diferença de até 1,4 segundo
• Depois da nona tentativa, nada. O receptor voltou menos de duas horas depois, e nenhum dos quatro pedidos chegou a ele pelo webhook
• "19 novas tentativas em 48 horas", que muitos guias ainda repetem, está desatualizado
• Um webhook adicionado no admin da Shopify não foi excluído depois de 36 falhas de entrega seguidas. A página do admin não mostrou falha, e nenhum e-mail chegou ao dono da loja
• Sobreviver a uma queda de mais de quatro horas exige duas coisas: algo que armazene os eventos e responda à Shopify enquanto seu servidor está fora do ar, e um job de conciliação pela Admin API. Para um webhook adicionado no admin, ou para um app pequeno, a menor mudança é um relay como o AnyHook: você troca uma URL

Cronograma medido

Os tempos contam a partir de X-Shopify-Triggered-At, o timestamp que a Shopify coloca no webhook.

Cinco das nove tentativas são gastas nos primeiros oito minutos. Elas cobrem uma oscilação passageira e fazem pouco contra um deploy quebrado: quando alguém está olhando o alerta, sobram quatro tentativas.

O cronograma parece fixo. Em cada etapa, os quatro pedidos chegaram com diferença de até 1,4 segundo entre si, então não há jitter visível. Um lote de pedidos que falha junto volta como o mesmo lote: o pico de uma promoção relâmpago retorna um minuto depois, depois três, depois oito.

As novas tentativas de um evento carregam o mesmo ID. No pedido que comparamos, o X-Shopify-Webhook-Id foi idêntico nas nove tentativas, o que faz dele uma chave segura para deduplicar.

A linha que importa é a de quatro horas. Quando seu endpoint volta, todo pedido das últimas quatro horas ainda está a caminho, na próxima tentativa agendada. Todo pedido mais antigo que isso nunca chega.

"19 novas tentativas em 48 horas" está desatualizado

Você ainda vai encontrar esse número, inclusive em guias que fornecedores de webhook publicaram este ano. Ele vem da política antiga da Shopify. A Shopify mudou o mecanismo em 10 de setembro de 2024 para 8 novas tentativas em 4 horas, e a documentação atual diz o mesmo. Nosso log concorda: a última tentativa veio às quatro horas, e no dia seguinte nada mais tinha chegado.

Se um runbook ou plano de recuperação seu parte de dois dias, o erro é de um fator de doze.

O que aconteceu com os pedidos

No webhook direto, as 36 entregas (quatro pedidos, nove tentativas cada) receberam 503. O receptor voltou a responder 200 1 hora e 37 minutos depois da última dessas tentativas, e a Shopify não tentou de novo. Nenhum dos quatro pedidos chegou a ele.

Nada nessa queda foi incomum. Um deploy ruim numa sexta à noite, corrigido antes da meia-noite, é igual. Quais pedidos você perde depende de quanto tempo ficou fora do ar. Numa queda de seis horas, os pedidos das duas primeiras horas somem do caminho do webhook, e os pedidos das quatro últimas chegam na próxima tentativa agendada, até duas horas depois de você voltar. Isso vale para um webhook que sobrevive à queda. Uma inscrição criada pela Admin API pode ser excluída no meio do caminho, e aí nada de novo é enviado até você recriá-la.

Rode isso durante uma promoção de Black Friday, quando seus servidores estão sob mais carga e cada hora concentra mais pedidos, e essas primeiras horas precisam ser preenchidas pela Admin API (backfill). Não há outro jeito de recuperá-las. Os passos estão em A Shopify excluiu sua inscrição de webhook.

O webhook continuou lá, e ninguém foi avisado

A documentação da Shopify diz que uma inscrição é excluída depois de 8 falhas consecutivas apenas se foi configurada pela Admin API, e que os avisos vão para o e-mail de emergência do desenvolvedor do app. Ela não menciona webhooks adicionados à mão no admin da Shopify, em Settings → Notifications → Webhooks (Configurações → Notificações → Webhooks). Esses não têm app por trás, e muitas vezes são eles que ligam uma loja a um ERP ou à logística.

Então fomos ver. Depois de 36 falhas de entrega seguidas, no dia seguinte:

• O webhook continuava na lista, sem nenhuma mudança
• A página do admin não mostrava histórico de entregas nem sinal de falha. Cada linha oferece editar, enviar teste e excluir
• Nenhum e-mail de aviso tinha chegado ao endereço do dono da loja

Um webhook que falhou em todas as entregas durante um dia tem a mesma aparência de um saudável. O único sintoma são os pedidos que faltam no sistema de destino. Uma inscrição criada pela Admin API falha de outro jeito: a Shopify a exclui.

Como sobreviver a uma queda de mais de quatro horas

Você precisa de algo que armazene os eventos e responda à Shopify enquanto seu servidor está fora do ar, e de um job de conciliação para o que ainda escapar. A própria documentação da Shopify recomenda construir esse job. Nós fazemos uma das opções abaixo, então pese nossa opinião de acordo.

Qual escolher:

• Você adicionou o webhook à mão, ou tem um app pequeno, e quer que os pedidos sobrevivam a uma noite ruim: coloque um relay na frente do seu endpoint. O AnyHook foi feito para esse caso. Uma URL muda e seu handler continua como está
• Você é uma equipe de plataforma com volume sério: o Hookdeck é o produto mais completo. Aqui está a comparação entre os dois
• Seu app já roda na AWS ou no Google Cloud: o EventBridge ou o Pub/Sub se encaixa no que você tem
• Em todos os casos: mantenha um job de conciliação para pedidos. Um relay move a linha de quatro horas para a janela de novas tentativas e a retenção dele, e a linha continua lá

O mesmo teste pelo AnyHook

O AnyHook é um relay de webhooks: você aponta um webhook para ele, ele armazena o evento, responde ao remetente e encaminha para seu servidor, tentando de novo quando seu servidor falha. Neste teste, cada pedido também foi para um segundo webhook, apontado para o AnyHook, que encaminhou para o mesmo receptor:

O AnyHook responde à Shopify com um 200 em cerca de um segundo, então a Shopify não tem nada para tentar de novo, e esse cronograma é o do próprio AnyHook contra o mesmo receptor com falha. Muito depois de as tentativas da Shopify no webhook direto terem acabado, a quinta tentativa encontrou o receptor saudável e entregou os três pedidos que ainda esperavam. A cópia do primeiro pedido já tinha chegado aos 35 minutos, por um deslize nosso explicado em Como testamos.

O salto adicionou de 0,5 a 0,9 segundo à primeira tentativa. A assinatura da Shopify sobreviveu a ele: o receptor verificou o X-Shopify-Hmac-SHA256 original nas cópias encaminhadas e todas as verificações passaram, então o código de verificação que você já tem continua funcionando. O AnyHook enviou e-mail na primeira entrega com falha e de novo na quinta seguida. A Shopify não enviou nenhum.

Isso rodou na nossa própria conta Enterprise. O tempo das novas tentativas é o mesmo em todos os planos. O que muda é quantas tentativas você tem e por quanto tempo pode fazer replay:

No Free, este teste teria sido diferente: as novas tentativas param aos 35 minutos, antes de o receptor voltar. Os pedidos ainda estariam no log, e você faria o replay deles à mão dentro de três dias. O Free também recusa eventos acima de 1.000 por dia, então não é o plano para uma promoção. O Pro não tem limite diário, e a quinta tentativa roda como rodou aqui.

Um relay é mais uma parte no caminho dos seus pedidos. O AnyHook armazena cada evento, com criptografia em repouso, antes de responder. Se não consegue armazenar um evento, ele responde 503 em vez de 200, e as próprias novas tentativas da Shopify assumem.

Como configurar

1. No AnyHook, crie um app e defina a URL do seu webhook atual como destino. Para olhar antes, sem criar conta, este comando retorna uma inbound_url ativa, uma chave de API e uma claim_url. O endpoint e seus eventos são excluídos após 7 dias, a menos que você abra a URL de claim e entre na conta:

   curl -X POST https://anyhook.net/api/v1/quickstart
   

2. No admin da Shopify, vá em Settings → Notifications → Webhooks (Configurações → Notificações → Webhooks) e clique em Create webhook (criar webhook). Escolha o evento, defina o formato como JSON e cole a URL de entrada.

3. Copie o segredo de assinatura mostrado nessa página para o segredo de assinatura da origem do app e envie um teste pelo menu do webhook. Ele deve aparecer no log do app, e uma requisição forjada recebe 401. Uma inscrição criada pelo seu app assina com o client secret do app.

Um agente de código com IA pode fazer o primeiro passo com npx -y anyhook-mcp.

FAQ

Quantas vezes a Shopify tenta de novo um webhook que falhou?

Oito vezes depois da primeira tentativa, ou seja, nove entregas no total, ao longo de quatro horas. Medimos tentativas em cerca de 2 s, 3 s, 1 min, 3 min, 8 min, 30 min, 1 h, 2 h e 4 h depois do evento.

A Shopify ainda tenta reenviar webhooks por 48 horas?

Não. As 19 novas tentativas em 48 horas dos guias antigos são anteriores a uma mudança que a Shopify fez em setembro de 2024. No nosso teste de novembro de 2026, a última tentativa veio às quatro horas.

A Shopify reenvia os webhooks quando meu servidor volta?

Só enquanto as tentativas de um evento ainda estão rodando. Um evento disparado menos de quatro horas antes de você voltar chega na próxima tentativa agendada. Um evento mais antigo não é enviado de novo, então você o busca na Admin API.

O que a Shopify considera uma entrega com falha?

Segundo a documentação da Shopify, qualquer resposta fora da faixa 200, incluindo redirecionamentos 3xx, e nenhuma resposta em cinco segundos, com um segundo reservado para a conexão. Nosso teste usou apenas respostas 503.

A Shopify exclui um webhook que continua falhando?

Uma inscrição criada pela Admin API é excluída após 8 falhas consecutivas, segundo a documentação da Shopify. No nosso teste, um webhook adicionado no admin da Shopify ainda estava na lista no dia seguinte a 36 falhas consecutivas.

A Shopify avisa quando um webhook falha?

Para inscrições de app, os e-mails de aviso vão para o endereço de emergência do desenvolvedor do app. Para o webhook que adicionamos no admin, nenhum e-mail chegou ao dono da loja e a página do admin não mostrou falha.

Como recupero os pedidos que a Shopify parou de tentar enviar?

Consulte a Admin API para a janela da queda e passe os resultados pelo seu handler normal, com a deduplicação ligada. Os passos estão em A Shopify excluiu sua inscrição de webhook.

Qual a melhor forma de não perder webhooks da Shopify quando meu servidor cai?

Coloque um relay de webhooks ou uma fila na frente do seu endpoint: ele responde à Shopify, armazena o evento e tenta de novo contra seu servidor num cronograma mais longo. Para um webhook adicionado no admin ou um app pequeno, o AnyHook é a menor mudança, uma URL com plano gratuito, e os planos pagos tentam de novo por mais tempo e não têm limite diário. O Hookdeck atende equipes de plataforma que precisam de transformações e fluxos de trabalho em equipe. Apps na AWS ou no Google Cloud podem enviar suas inscrições para o EventBridge ou o Pub/Sub. Em todos os casos, mantenha um job de conciliação pela Admin API.

Como testamos

Rodamos isto em 2 de novembro de 2026, numa loja de desenvolvimento da Shopify, com a versão 2026-10 da API, tópico orders/create. Os dois webhooks foram adicionados no admin. O receptor era um Cloudflare Worker que registrava cada requisição e respondia 503 até as 17:43 UTC, e depois 200. Os quatro pedidos foram feitos entre 11:46 e 12:06 UTC.

Horários exatos de chegada no webhook direto, em segundos depois de X-Shopify-Triggered-At:

Duas coisas saíram imperfeitas. Um deslize nosso deixou o receptor no ar por alguns minutos por volta das 12:20 UTC. Nenhuma tentativa direta caiu dentro dessa janela, mas a cópia do primeiro pedido pelo AnyHook caiu, então esse pedido ficou de fora dos resultados do AnyHook. E o receptor só começou a verificar assinaturas no meio do teste, então as primeiras tentativas nos dois caminhos não foram verificadas.

Não testamos um timeout nem uma conexão recusada, só um 503 rápido. Não testamos uma inscrição criada pela Admin API, então a regra de exclusão acima vem da documentação da Shopify. Não testamos uma loja em produção nem volume alto. Quatro pedidos é uma amostra pequena, embora um cronograma tão regular dificilmente seja ruído. A Shopify pode mudar qualquer um desses pontos, então confira a data acima.