Como a entrega de webhook funciona
O Shopify dispara um evento ORDERS_PAID no momento em que o pagamento é capturado. O evento cai num tópico do Google Cloud Pub/Sub, o worker do Alva puxa a mensagem, escreve as linhas Customer e Purchase no PostgreSQL, depois envia o e-mail de entrega pelo Postmark ou MailerToGo. O buffer do Pub/Sub é o que torna isso confiável: se um deploy estiver em andamento ou o banco estiver brevemente lento, a mensagem espera na fila e é redentregue até o worker confirmar o sucesso.
Diagrama horizontal simples de pipeline com cinco estágios rotulados: Shopify ORDERS_PAID → tópico Google Cloud Pub/Sub → worker do Alva → PostgreSQL (Customer + Purchase) → envio de e-mail (Postmark / MailerToGo). Use o teal/azul da marca Alva. Sem dados reais de cliente.
Razões comuns para atraso
Carga pesada na fila do Pub/Sub
Durante grandes promoções, o tópico pode segurar milhares de mensagens pendentes. O worker do Alva drena em ordem, então um pedido no fim de uma fila de 5.000 mensagens espera sua vez. A latência aqui geralmente fica abaixo de dois minutos.
Checagem antifraude segurando o e-mail
Quando as checagens antifraude estão habilitadas, o worker escreve o pedido em FraudCheckQueue e pausa a entrega até a Risk API do Shopify responder. A maioria das checagens resolve em segundos; pedidos roteados para revisão manual esperam até você aprová-los. Chaves de licença nunca são atribuídas antes da aprovação antifraude.
Regeneração de ZIP de pack grande
Se o produto é um pack e um dos arquivos mudou desde que o último ZIP cacheado foi construído, o Alva regenera o arquivo no R2 antes de enviar o e-mail. Packs de vários gigabytes podem levar minutos.
Configuração de e-mail por produto mudada no meio do voo
Se você alternar um template de e-mail por produto ou desabilitar e-mails para um produto enquanto um pedido está em andamento, o worker relê ProductEmailSettings na próxima tentativa. O pedido ainda completa — o e-mail simplesmente usa a nova regra.
Retentativas de webhook do Shopify
O Shopify retenta um webhook falho até 19 vezes ao longo de cerca de 48 horas, com backoff entre tentativas. Se a primeira entrega bateu no Alva durante um deploy, o pedido pode não aparecer até a próxima retentativa ter sucesso — geralmente em 5 a 10 minutos.
O que fazer se já passaram mais de 5 minutos
Cinco minutos cobre a vasta maioria dos casos. Passado essa janela, percorra esta checklist:
- Confirme que o pedido está pago no Shopify — pedidos pendentes ou autorizados nunca disparam
ORDERS_PAID. - Abra a lista de pedidos do admin do Alva. Retido significa que a antifraude está bloqueando a entrega; Processando significa que o worker ainda está nele.
- Confira Configurações → E-mail para confirmar que a entrega de e-mail está habilitada e que um remetente verificado está configurado.
- Se o pedido está faltando completamente, recorra a Encontre o link de download de um cliente para redisparar a entrega manualmente.
Perguntas frequentes
O Pub/Sub bufferiza webhooks durante deploys, quedas e picos de tráfego para que um pedido pago nunca seja descartado. O worker só confirma a mensagem depois que a linha Purchase é escrita.
Não. A página de agradecimento usa um token de download provisório da extensão de checkout, então arquivos aparecem instantaneamente mesmo quando o webhook ORDERS_PAID ainda está em voo.
Até 19 vezes ao longo de cerca de 48 horas, com backoff exponencial. Desde que o Alva eventualmente retorne sucesso, o pedido processa normalmente.
Veja também
Foi útil?
Última atualização 2026-05-06