- O Webhook envia automaticamente dados da sua loja para sistemas externos — CRM, e-mail marketing, ERP ou qualquer serviço que receba dados via API — sempre que um evento acontece, como um novo pedido, um novo cliente ou um produto atualizado.
- Você cria cada webhook escolhendo qual evento o dispara, para qual endereço os dados vão e o que será enviado, tudo pelo painel administrativo, sem precisar de desenvolvimento sob medida.
- O envio pode ser imediato (na hora do evento) ou programado em intervalos, e cada disparo fica registrado para você acompanhar e reenviar em caso de falha.
- Recurso voltado a quem precisa integrar a loja com outras ferramentas usadas no dia a dia do negócio.
Passo a Passo por Escrito
1. Acesse as configurações gerais e habilite o módulo
Acesse o painel administrativo e vá em Lojas → Configuração → Mageplaza Extensions → Webhook.
Abra o grupo Geral (General) e confirme que o campo Habilitar (Enable) está como Sim (Yes).
Por padrão, o módulo já vem habilitado. Você só precisa alterar esse campo se quiser desligar todos os webhooks de uma vez.
Clique em Salvar configuração (Save Config) no canto superior direito.
Resultado esperado: a mensagem "A configuração foi salva" é exibida no topo da tela e o módulo fica ativo para enviar webhooks.
2. Ajuste alertas, reenvio e retenção de registros (opcional)
Ainda no grupo Geral (General), ajuste as opções abaixo conforme a sua necessidade.
| Campo | O que preencher |
|---|---|
| Carrinho abandonado após (Abandoned Cart After) | Número de horas sem atividade para um carrinho ser considerado abandonado. Padrão: 10. Só importa se você for usar webhooks de carrinho abandonado. |
| Manter registros (Keep logs) | Quantos registros de envio o sistema guarda por webhook. Padrão: 10. Deixe vazio ou 0 para não apagar registros antigos automaticamente. |
| Alertar em caso de erro (Alert on Error) | Selecione Sim (Yes) para receber um e-mail sempre que um envio falhar. |
| Enviar para os e-mails (Send To Email Address(es)) | Endereços que receberão os alertas de erro, separados por vírgula. |
| Modelo de e-mail (Email Template) | Modelo usado no e-mail de alerta. Use o modelo padrão ou crie um em Marketing → Modelos de E-mail. |
| Reenvio automático de webhooks com erro (Auto-replay errored hook) | Selecione Sim (Yes) para o sistema tentar reenviar sozinho os envios que falharam. |
| A cada quantas horas (After every hour(s)) | Aparece quando o reenvio automático está ligado. Define de quantas em quantas horas o reenvio acontece. Padrão: 3. |
Em Manter registros (Keep logs), se você deixar o campo vazio ou com zero, nenhum registro antigo é apagado automaticamente — o histórico pode crescer sem limite.
O reenvio automático depende do agendador de tarefas automáticas da loja estar ativo. E, para os e-mails de alerta chegarem corretamente e não caírem em spam, é recomendado ter o envio de e-mails (SMTP) configurado na loja.
Resultado esperado: as opções de alerta, reenvio e retenção ficam salvas e passam a valer para os próximos envios.
3. Escolha como os webhooks serão enviados
Ainda na tela de configurações, abra o grupo Programação de envio (Schedule For Cron).
No campo Programação de envio (Schedule For Cron), escolha uma das opções:
| Opção | Comportamento |
|---|---|
| Desativado (Disable) | Envia os dados na hora exata em que o evento acontece. É o padrão e atende à maioria dos casos. |
| A cada minuto (Every Minute) | Os eventos entram em uma fila e são enviados a cada minuto. |
| Diário (Daily) | Envia uma vez por dia, no horário definido em Horário de início. |
| Semanal (Weekly) | Envia uma vez por semana, no horário definido em Horário de início. |
| Mensal (Monthly) | Envia uma vez por mês, no horário definido em Horário de início. |
Ao escolher Diário, Semanal ou Mensal, defina também o Horário de início (Start Time). Exemplo: 02,30,00.
Programar o envio para horários de menor tráfego (como a madrugada) reduz o impacto na loja durante picos de venda, como Black Friday. Em compensação, o sistema externo não recebe os dados em tempo real.
Nas opções programadas, o envio depende do agendador de tarefas automáticas da sua loja estar ativo. Se ele estiver parado, os webhooks programados não saem e ficam acumulados na fila.
No modo Desativado (Disable), o webhook é enviado junto com o salvamento do pedido, cliente ou produto. Se o sistema de destino demorar a responder, esse salvamento pode ficar um pouco mais lento.
Resultado esperado: o modo de envio fica definido, valendo para os webhooks da loja.
4. Salve as configurações gerais
Clique em Salvar configuração (Save Config) no canto superior direito da tela.
Resultado esperado: a mensagem "A configuração foi salva" é exibida no topo da tela.
5. Abra o gerenciador de webhooks e adicione um novo
Vá em Sistema → Webhook → Gerenciar Hooks (Manage Hooks).
Nessa tela ficam todos os webhooks já criados, com nome, situação, visão de loja e tipo de evento. Você pode editar, excluir ou alterar o status dos webhooks existentes, além de filtrar e ordenar a listagem.
Clique em Adicionar novo (Add New) e selecione o tipo de evento que deve disparar o webhook. Os tipos disponíveis incluem:
- Pedidos: Novo pedido (New Order), Comentário em pedido (New Order Comment), Nova fatura (New Invoice), Novo envio (New Shipment), Novo reembolso (New Credit Memo)
- Clientes: Novo cliente (New Customer), Atualizar cliente (Update Customer), Excluir cliente (Delete Customer), Login de cliente (Customer Login)
- Produtos: Novo produto (New Product), Atualizar produto (Update Product), Excluir produto (Delete Product)
- Categorias: Nova categoria (New Category), Atualizar categoria (Update Category), Excluir categoria (Delete Category)
- Outros: Inscrição na newsletter (Subscribe), Cancelamento de inscrição (Unsubscribe), Carrinho abandonado (Abandoned Cart), Nova avaliação (New Review)
O tipo de evento define exatamente quando o webhook dispara. Editar um produto que já existe, por exemplo, aciona o tipo Atualizar produto (Update Product) — e não Novo produto (New Product).
Resultado esperado: a tela de criação do webhook é exibida, dividida nas abas Geral (General) e Ações (Actions).
6. Preencha as informações básicas do webhook
Na aba Geral (General) do webhook, preencha os campos de identificação:
| Campo | O que preencher |
|---|---|
| Nome (Name) | Um nome que ajude a identificar esse webhook depois. Aparece nos alertas e nos registros. Exemplo: Envio de pedidos para o ERP. |
| Status (Status) | Deixe como Ativado (Enable) para o webhook funcionar. |
| Visões de loja (Store Views) | Selecione as lojas em que esse webhook deve valer. Campo obrigatório: sem ao menos uma visão de loja, o webhook não dispara. |
| Prioridade (Priority) | Ordem de execução quando há vários webhooks para o mesmo evento. Quanto menor o número, mais cedo ele é executado; 0 é a maior prioridade. |
| Status do pedido (Order Status) | Aparece apenas nos eventos de pedido. Selecione em quais status do pedido o envio deve ocorrer (por exemplo, quando o pedido é pago ou faturado). |
Um webhook configurado para uma visão de loja específica não dispara para eventos de outra loja. Confirme que a visão de loja escolhida corresponde à loja onde o evento acontece.
Nos webhooks de pedido, se nenhum item estiver marcado em Status do pedido (Order Status), o webhook não dispara. Selecione pelo menos um status.
Resultado esperado: as informações básicas do webhook ficam definidas e prontas para receber a configuração de destino.
7. Defina o destino e o conteúdo enviado
Na aba Ações (Actions) ficam as informações sobre para onde e como os dados serão enviados.
| Campo | O que preencher |
|---|---|
| URL de destino (Payload URL) | Endereço do sistema externo que vai receber os dados. Campo obrigatório. |
| Método (Method) | Método da requisição. Se deixar em branco, normalmente assume GET. Veja a tabela abaixo. |
| Autenticação (Authentication) | Tipo de autenticação exigido pelo destino. Deixe em branco se não for necessário. |
Métodos disponíveis:
| Método | Quando usar |
|---|---|
| GET | Para obter dados do destino. Não envia conteúdo no corpo da requisição. |
| POST | Para criar um novo registro no sistema externo. É o método mais comum em integrações por webhook. |
| PUT | Para atualizar um registro existente no destino. |
| PATCH | Para aplicar atualizações parciais a um registro existente. |
| DELETE | Para remover um registro do sistema externo. |
O menu de método também oferece as opções HEAD, OPTIONS, CONNECT e TRACE, usadas em casos avançados conforme a documentação da API de destino.
Tipos de autenticação:
| Tipo | Comportamento |
|---|---|
| Em branco | Nenhuma autenticação é enviada. Use quando o destino for público ou já estiver autenticado por um cabeçalho. |
| Basic | Exibe os campos Usuário (Username) e Senha (Password), enviados junto com a requisição. |
| Digest | Solicita verificação adicional. Oferece mais segurança que o Basic. |
Ao usar autenticação Basic ou Digest, certifique-se de que o sistema de destino utiliza HTTPS. Credenciais enviadas por conexões HTTP comuns podem ser interceptadas.
Cabeçalhos, tipo de conteúdo e corpo:
| Campo | O que preencher |
|---|---|
| Cabeçalhos (Headers) | Clique em Adicionar (Add) para incluir cabeçalhos exigidos pelo destino. Exemplo: nome Authorization, valor Token token="SuaAPIKey". |
| Tipo de conteúdo (Content Type) | Tipo do conteúdo enviado (ex: application/json). Para o método GET, pode ficar em branco. |
| Corpo (Body) | Disponível para POST, PUT, PATCH e similares. É o conteúdo que será enviado na requisição. |
No Corpo (Body) e na URL de destino (Payload URL) você pode inserir dados reais do evento usando variáveis no formato {{ item.xxx }} — por exemplo, o número do pedido ou o e-mail do cliente. Use o botão Inserir Variável (Insert Variable) para adicionar as variáveis disponíveis sem erro de digitação, e o botão Pré-visualização (Preview) para conferir como o conteúdo final ficará.
Para validar a configuração antes de ligar ao sistema final, aponte a URL de destino (Payload URL) para um serviço gratuito de inspeção de requisições, como webhook.site ou webhook-test.com. Eles geram uma URL temporária que mostra, em tempo real, o que está chegando.
Se uma variável estiver escrita errada ou apontar para um dado que não existe naquele evento, o webhook é enviado mesmo assim, mas com o conteúdo em branco — sem mensagem de erro na tela. Se o destino estiver recebendo dados vazios, revise as variáveis do Corpo (Body) e da URL de destino (Payload URL).
O serviço webhook-test.com funciona apenas com o método POST. Requisições enviadas por GET aparecem sem conteúdo, o que pode dar a falsa impressão de que o webhook não está funcionando.
Resultado esperado: o destino, o método e o conteúdo do webhook ficam definidos, prontos para serem salvos.
8. Salve o webhook
Clique em Salvar (Save) no canto superior direito da tela.
Resultado esperado: a mensagem de confirmação é exibida e o novo webhook aparece na lista em Sistema → Webhook → Gerenciar Hooks (Manage Hooks), pronto para disparar quando o evento configurado acontecer.
9. Acompanhe os envios pelos registros (Logs)
Os registros mostram o status de cada envio e ajudam a identificar erros. Há duas formas de consultá-los:
- De um webhook específico: acesse Sistema → Webhook → Gerenciar Hooks (Manage Hooks), edite o webhook e abra a aba Registros (Logs).
- De todos os webhooks juntos: acesse Sistema → Webhook → Registros (Logs).
Cada registro mostra o nome do webhook, a situação do envio (Success ou Error), o tipo de evento e a mensagem retornada pelo destino. Em cada registro você pode:
- Clicar em Ver (View) para acessar os detalhes do envio, incluindo os dados enviados e a resposta recebida.
- Clicar em Reenviar (Replay) para reenviar manualmente um envio que falhou.
Os registros são removidos automaticamente quando passam do limite definido em Manter registros (Keep logs). Aumente esse limite se precisar guardar um histórico mais longo.
Resultado esperado: você consegue acompanhar o histórico de envios e identificar rapidamente os que tiveram sucesso e os que falharam.
Validação e Testes
Após concluir a configuração, execute os testes abaixo para confirmar o funcionamento correto.
Teste 1 — Disparar o evento com uma URL de teste
Ação:
- Acesse webhook.site ou webhook-test.com e copie a URL única gerada pelo serviço.
- Edite o webhook em Sistema → Webhook → Gerenciar Hooks (Manage Hooks) e cole essa URL no campo URL de destino (Payload URL).
- Confirme que o Método (Method) está como POST e salve.
- Provoque o evento configurado — por exemplo, se o webhook for de Novo pedido (New Order), crie um pedido de teste.
- Volte ao serviço de teste e verifique se a requisição chegou.
Resultado esperado: a requisição aparece no serviço de teste em tempo real, contendo os dados do evento (número do pedido, dados do cliente, itens etc).
Teste 2 — Conferir o histórico de envios
Ação: acesse Sistema → Webhook → Registros (Logs) e localize o disparo que você acabou de provocar. Confira a situação e a resposta recebida do destino.
Resultado esperado: o envio aparece na lista com situação Success. Ao clicar em Ver (View), você visualiza os dados enviados e a resposta do destino.
Teste 3 — Reenviar um envio com erro
Ação: caso algum envio apareça com situação Error, corrija o problema no destino e use a ação Reenviar (Replay) na tela de Registros (Logs) para enviar novamente aquele disparo.
Resultado esperado: após o reenvio, um novo registro é criado e, com o destino corrigido, ele aparece com situação Success.
Se não funcionar, verifique:
- O módulo está habilitado em Lojas → Configuração → Mageplaza Extensions → Webhook → Habilitar (Enable) = Sim (Yes).
- O webhook está com Status (Status) = Ativado (Enable).
- A Visão de loja (Store Views) do webhook corresponde à loja onde o evento aconteceu.
- O tipo do evento está correto (por exemplo, editar um produto existente exige um webhook de Atualizar produto (Update Product)).
- Nos webhooks de pedido, o status do pedido está entre os selecionados em Status do pedido (Order Status).
- A URL de destino (Payload URL) está correta e acessível publicamente (URLs internas ou em rede local não funcionam).
- As variáveis do Corpo (Body) e da URL de destino (Payload URL) estão corretas (senão o destino recebe conteúdo vazio).
- Se você escolheu um modo programado em Programação de envio (Schedule For Cron), o agendador de tarefas automáticas da loja está ativo.
Durante os testes, nunca utilize credenciais de autenticação reais de sistemas em produção. Use ambientes de homologação ou tokens temporários para evitar a exposição de dados sensíveis.
Pronto! Dessa forma realizamos a configuração do Webhook em sua loja virtual Magento 2.
Observações Importantes
- Um webhook por evento e por destino: cada webhook é vinculado a um único tipo de evento e a um único destino. Se você precisa enviar os novos pedidos para o ERP e para o CRM, crie dois webhooks separados — ambos com o evento Novo pedido (New Order), cada um com sua URL.
- Escopo por loja: cada webhook vale apenas para as visões de loja selecionadas. Um webhook restrito a uma loja não dispara para eventos de outra.
- Modo programado depende do agendador da loja: ao usar qualquer opção diferente de Desativado (Disable) em Programação de envio (Schedule For Cron), os envios só acontecem se o agendador de tarefas automáticas da loja estiver ativo.
- Envio imediato pode adicionar atraso: no modo Desativado (Disable), o webhook é enviado junto com o salvamento do pedido, cliente ou produto. Se o destino for lento, o salvamento pode demorar mais.
- Falha de variável é silenciosa: se uma variável do Corpo (Body) ou da URL de destino (Payload URL) estiver incorreta, o webhook é enviado com conteúdo vazio, sem apresentar erro na tela. Acompanhe os Registros (Logs) e o que chega no destino.
- Webhook de pedido depende do status: webhooks do tipo pedido só disparam quando o pedido está em um dos status selecionados em Status do pedido (Order Status).
- Carrinho abandonado é global: o tempo definido em Carrinho abandonado após (Abandoned Cart After) vale para todos os webhooks de carrinho abandonado da loja. Não é possível usar tempos diferentes para webhooks diferentes desse tipo.
- Retenção de registros: por padrão, apenas os 10 envios mais recentes de cada webhook são mantidos; os mais antigos são removidos automaticamente. Aumente o valor em Manter registros (Keep logs) se precisar guardar mais histórico.
- Reenvio: envios com erro podem ser reenviados manualmente pela ação Reenviar (Replay) nos Registros (Logs), ou automaticamente, ativando o Reenvio automático de webhooks com erro (Auto-replay errored hook).
Referências e Relacionados
- Credenciais API — visão geral: entenda como gerenciar conexões e credenciais de integrações com sistemas externos no admin, tema diretamente ligado à configuração de webhooks.
- Configuração de e-mails transacionais (SMTP): garante que os alertas de erro do webhook cheguem corretamente à sua caixa de entrada, sem cair em spam.
- Gerenciamento de pedidos: como os eventos de pedido são um dos gatilhos mais comuns de webhook, esta documentação ajuda a entender o fluxo de pedidos que dispara os envios.
Caso tenha ficado alguma dúvida entre em contato com nosso time de suporte através do chat online dentro da sua loja virtual ou através do e-mail web@tryideas.com.br