Configurar Webhooks no Magento 2 — Mageplaza Webhook
- Este guia ensina como configurar a extensão Mageplaza Webhook no Magento 2.
- Webhooks permitem que sua loja envie notificações automáticas para sistemas externos quando eventos específicos ocorrem, como novos pedidos, cadastros de clientes ou atualizações de produtos.
- A extensão permite configurar gatilhos, métodos HTTP, autenticação, headers customizados e agendamento via Cron.
- Ideal para integrar o Magento com ERPs, CRMs, plataformas de automação de marketing e outros serviços externos.
Passo a Passo
1. Acesse as Configurações Gerais
No painel administrativo, acesse Sistema > Webhook > Configuração.
| Campo | Explicação/Recomendação |
|---|---|
| Habilitar | Selecione Sim para ativar o módulo ou Não para desativá-lo. |
| Abandoned Cart After | Defina o tempo em minutos após o qual um carrinho será considerado abandonado. Valores recomendados: 1, 6, 10, 12 ou 24 minutos. |
| Keep Logs | Informe o número máximo de logs que o sistema deve manter. Ao atingir o limite, os registros mais antigos são removidos automaticamente de forma diária. |
| Alert on Error | Selecione Yes para receber notificações por e-mail quando ocorrer erro no envio de um webhook. |
| Auto-replay errored hook |
Permite *repetir automaticamente webhooks com status "Error" em um horário agendado. |
| After every hour(s) | Quando "Auto-replay errored hook" está ativo (Sim), o campo "After every hour(s)" aparece para definir quantas horas após o erro o sistema tentará reenviar o webhook automaticamente via cron. |
| Send to | Insira os endereços de e-mail que receberão os alertas de erro. Separe múltiplos endereços por vírgula. |
| Email Template | Selecione o template de e-mail para os alertas. Utilize o template padrão Default Mageplaza Webhook Email Template ou crie um personalizado em Marketing > Email Templates. |
Resultado esperado: após salvar, o módulo estará ativo e pronto para receber a criação de hooks individuais.
2. Configure o Agendamento via Cron (opcional)
Ainda na tela de configurações, localize a seção Schedule For Cron.
| Campo | Explicação/Recomendação |
|---|---|
| Schedule For Cron | Define quando os webhooks serão disparados. Veja as opções abaixo. |
| Hora de início | Exibido apenas quando Diário, Semanal ou Mensal estão selecionados. Define o horário exato em que a sincronização será executada. Exemplo: 02:30:00. |
As opções disponíveis para Schedule For Cron são:
| Opção | Comportamento |
|---|---|
| Desabilitado | Envia os dados imediatamente após o evento. Configuração padrão e recomendada para a maioria dos casos. |
| Every Minute | Sincroniza os dados a cada minuto. |
| Diário | Sincroniza uma vez ao dia, no horário definido em Start Time. |
| Semanal | Sincroniza toda segunda-feira. |
| Mensal | Sincroniza no primeiro dia de cada mês. |
Utilizar o Cron permite agendar o envio para horários de menor tráfego, reduzindo o impacto na performance da loja durante eventos de alto volume.
Se o envio agendado resultar em erro, o sistema enviará automaticamente um e-mail de notificação ao administrador.
Resultado esperado: o agendamento estará configurado conforme a frequência selecionada.
3. Salve as Configurações Gerais
Clique em Save Config no canto superior direito da tela.
As configurações gerais foram salvas com sucesso. Agora você pode criar e gerenciar hooks individuais.
4. Acesse o Gerenciamento de Hooks
No painel administrativo, acesse Sistema > Webhook > Manage Hooks.
Nessa tela você verá todos os webhooks criados, com informações como Nome, Status, Store View, Entidade, Data de Criação e Data de Atualização. As ações disponíveis na listagem são excluir hooks via Excluir, alterar o status via Alterar Status e editar um hook existente clicando em Editar.
Também é possível filtrar resultados, alterar o Store View e exibir ou ocultar colunas diretamente na grid.
5. Crie um Novo Hook
Clique no botão Adicionar Novo no canto superior direito e selecione o tipo de evento que irá disparar o webhook.
Os eventos disponíveis incluem: New Order, New Product, Update Product, Delete Product, entre outros. Cada evento criará um hook independente com suas próprias configurações.
6. Preencha a Aba "General" do Hook
| Campo | Explicação/Recomendação |
|---|---|
| Nome | Insira o nome do hook. Este nome será exibido nos e-mails de notificação e na listagem de logs. |
| Situação | Selecione Habilitar para ativar o hook imediatamente após salvar. |
| Store View | Selecione em qual Store View o hook será aplicado. Se nenhuma Store View for selecionada, o hook não funcionará. |
| Prioridade | Defina a ordem de execução quando há múltiplos hooks ativos. Quanto menor o número, maior a prioridade. O valor 0 representa a maior prioridade possível. |
7. Configure a Aba "Ações" do Hook
| Campo | Explicação/Recomendação |
|---|---|
| Payload URL | Insira a URL para a qual o Magento enviará as requisições. Campo obrigatório. Você pode incluir variáveis dinâmicas ao final da URL utilizando o botão Inserir Variável. |
| Método | Selecione o método HTTP da requisição. Se deixado em branco, o padrão será GET. Veja a tabela de métodos abaixo. |
| Authentication | Selecione o tipo de autenticação exigido pelo servidor de destino. Deixe em branco se não for necessária autenticação. |
| Método | Uso recomendado |
|---|---|
| GET | Obtém dados do servidor. Não envia body na requisição. |
| POST | Cria um novo objeto. Recomendado para a maioria das integrações. |
| PUT | Atualiza um objeto existente. |
| DELETE | Remove um objeto. |
| PATCH | Aplica modificações parciais a um objeto. |
| HEAD | Igual ao GET, mas retorna apenas os cabeçalhos, sem body. |
| CONNECT | Estabelece um túnel TCP/IP, geralmente utilizado para HTTPS via proxy. |
| OPTIONS | Descreve os métodos e operações suportados pelo servidor na URL especificada. |
| TRACE | Repete a requisição para rastrear alterações feitas por servidores intermediários. |
| Tipo | Comportamento |
|---|---|
| Nenhuma (em branco) | Nenhuma autenticação será enviada. Use quando a API de destino for pública ou já autenticada via header. |
| Basic | Exibe campos de Username e Password. As credenciais são enviadas junto à requisição. |
| Digest | Solicita informações adicionais de verificação com maior segurança que o Basic. |
| Campo | Explicação/Recomendação |
|---|---|
| Cabeçalhos | Clique em Adicionar para incluir cabeçalhos necessários para a chamada de API. Exemplo: Nome Authorization, Valor Token token="SuaAPIKey". |
| Content-type | Selecione o tipo de conteúdo a ser enviado. Para o método GET, pode ser deixado em branco. |
| Body | Disponível para métodos como POST e PUT. Insira o conteúdo que será enviado na requisição. Utilize Inserir Variáveis para selecionar variáveis dinâmicas. Clique em Pré-visualização para visualizar o resultado final das variáveis configuradas. |
O teste no webhook-test.com funciona apenas com o método POST. Requisições enviadas com GET não exibirão body e podem aparecer com tamanho 0 bytes, indicando que nenhum dado foi transmitido.
Resultado esperado: o hook estará completamente configurado com URL, método, autenticação e body definidos.
8. Salve o Hook
Clique em Save no canto superior direito.
O hook foi criado e passará a disparar automaticamente sempre que o evento configurado ocorrer na loja.
9. Visualize e Gerencie os Logs
Os logs registram todas as atividades dos webhooks, permitindo monitorar o status de cada envio e depurar erros.
Para visualizar os logs de um hook específico, acesse Sistema > Webhook > Manage Hooks, localize o hook desejado e clique em Editar, depois em Registros.
Para visualizar os logs de todos os hooks em um único painel, acesse Sistema > Webhook > Registros.
Cada registro exibe as informações Nome, Status, Entidade e Mensagem. Clique em View para acessar os detalhes completos de um log. Para reenviar um webhook que falhou, utilize a ação Replay.
Os logs são removidos automaticamente quando atingem o limite configurado no campo Keep Logs das configurações gerais.
Validação e Testes
Para confirmar que o webhook está funcionando corretamente, siga os passos abaixo:
- Acesse https://webhook-test.com ou https://webhook.site/ e copie a URL única gerada pelo serviço.
- No painel administrativo, edite o hook criado e cole a URL no campo Payload URL.
- Certifique-se de que o Method está configurado como POST.
- Salve o hook e realize a ação correspondente ao evento configurado, como criar um pedido de teste na loja.
- Volte para o site e verifique se a requisição foi recebida com os dados corretos.
- No painel administrativo, acesse Sistema > Webhook > Registros e confirme que o registro foi criado com status de sucesso.
Se a requisição apareceu no webhook-test.com com os dados do evento e o log exibe status de sucesso, o webhook está funcionando corretamente.
Caso o webhook não seja disparado, verifique se o módulo está habilitado nas configurações gerais, se o hook está com status Habiltiado e se a URL de destino está acessível publicamente.
Nunca utilize credenciais de autenticação reais durante os testes. Utilize ambientes de homologação ou tokens temporários para evitar a exposição de dados sensíveis.
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