Como criar um Webhook para Integrações com seus produtos

Webhooks são uma forma eficiente de integrar sua plataforma com sistemas externos, recebendo notificações automáticas sempre que determinados eventos acontecem.

Neste artigo, você vai aprender a criar um webhook, configurar os eventos que deseja monitorar e testar se ele está funcionando corretamente.

Acessando a Área de Integrações

• No menu lateral principal, clique em Integrações.

• Dentro da página de Integrações, selecione a opção Webhook.

Visualizando Webhooks Existentes

• Se você já tiver webhooks ativos, eles serão listados na tela em colunas como:

  • PRODUTO

  • NOME DO WEBHOOK

  • URL

  • STATUS

• Caso ainda não tenha criado nenhum, a página estará vazia.

Criando um Novo Webhook

• Clique no botão “Criar webhook” no canto superior da tela.

• Um modal lateral será aberto com os seguintes campos de configuração:

Dados do Webhook

• Nome*
  Escolha um nome interno para identificar esse webhook.

• URL do Webhook*
  Endereço (endpoint) para o qual enviaremos as notificações.

• Autorização*
  Defina um token único de segurança. Esse token será enviado em cada requisição no header Authorization, garantindo que apenas a Ecompay possa acessar sua URL.

Testar Webhook

Logo abaixo, há o botão “Testar webhook”, que abre um novo modal:

• Escolha um evento entre os disponíveis.

• Clique em “Disparar teste”.

• Enviaremos um exemplo (payload fictício) para a URL informada, via requisição HTTP POST, para que você possa validar a integração.

Selecionar Produtos

• Você deve selecionar os produtos nos quais o webhook será aplicado.

• Se quiser aplicar o webhook para todos os produtos, basta ativar o toggle correspondente. Novos produtos serão incluídos automaticamente.

Selecionar Eventos

Escolha os eventos que deseja monitorar. Sempre que um dos eventos acontecer, um aviso será enviado para sua URL.

Eventos disponíveis:

• Compra aprovada – disparado quando o pagamento de uma compra é confirmado.

• Reembolso – quando um reembolso é realizado com sucesso.

• Chargeback – notifica em caso de estorno pelo banco.

• Fatura da assinatura vencida – quando uma fatura de assinatura não é paga até a data de vencimento.

• Assinatura criada – quando uma nova assinatura é iniciada.

• Assinatura renovada – disparado a cada renovação automática da assinatura.

• Notificações de renovação da assinatura – alertas enviados antes da renovação acontecer.

• Assinatura expirada – notifica quando uma assinatura chega ao fim do período e não é renovada.

• Mudança de status da entrega – para produtos físicos, avisa quando o status da entrega muda.

• Notificação de assinatura – pode ser usado para eventos genéricos ligados a assinaturas.

💡 Escolha apenas os eventos que sejam relevantes para a lógica do seu sistema externo. Por exemplo, se você precisa registrar clientes que concluíram uma compra, selecione "Compra aprovada". Para controlar o ciclo de vida de uma assinatura, selecione os eventos de assinatura.

Ativar Webhook

O webhook vem ativado por padrão.

• Se você não quiser ativá-lo imediatamente, será necessário desativar o toggle de ativação.
• Dessa forma, o webhook será apenas salvo e não entrará em funcionamento até que você ative posteriormente.

Depois de preencher todos os campos e configurações:

• Clique no botão "Aplicar" no final do modal para salvar seu webhook.