Criando seu webhook

O que são os webhooks

Webhooks são notificações enviadas pela Elix quando um evento acontece. Em vez de consultar a API repetidamente, sua aplicação recebe uma requisição POST na URL cadastrada no Painel.

Dessa forma, seu backend pode atualizar o status de uma cobrança, confirmar um recebimento ou iniciar outro processamento assim que a informação estiver disponível.

Como cadastrar seu webhook na Elix

Este passo a passo considera que sua conta PJ já está aprovada e que você possui acesso à Área do Cliente.

1. 1

   Acesse sua conta

   Entre na Área do Cliente com o usuário responsável pela integração.

   

2. 2

   Abra Minha conta

   Abra o menu do usuário no canto superior direito, selecione Minha conta e acesse a área de integrações.

   

3. 3

   Gere suas credenciais

   Na aba Credenciais API, gere o par de API Key e Secret Key caso sua integração ainda não possua uma credencial ativa. Guarde os valores em um local seguro antes de continuar.

   

4. 4

   Abra a aba Webhooks

   Ao lado de Credenciais API, selecione Webhooks. O Painel organiza os cadastros por tipo: contas, recebimentos, pagamentos, reembolsos, transferências internas, saldo e taxas. Os envios acontecem em Recebimentos(Pix recebido) e Contas (conta aprovada).

   

5. 5

   Informe a URL e as credenciais

   Clique em Novo webhook ou em Cadastrar no tipo desejado. Selecione o tipo, informe uma URL HTTPS pública e, se necessário, defina API Key e Secret Key nos campos próprios para autenticação Basic. Endereços de rede interna são recusados. Nunca inclua usuário ou senha na URL.

   

6. 6

   Crie o webhook

   Revise os dados e clique em Criar webhook. O cadastro aparecerá como ativo na lista e poderá ser testado, editado ou excluído pelo próprio Painel.

Mais de um webhook de recebimento

Você pode cadastrar até 3 webhooks de recebimento, por exemplo, um para a loja, outro para o ERP e outro para o aplicativo. Os demais tipos aceitam um webhook cada. Dê um nome a cada cadastro para identificar o sistema no Painel e no histórico de envios.

O controle é seu: antes de dar baixa, confira seQRCodeInfos.ConciliationId corresponde a uma cobrança criada pelo seu sistema. Se não corresponder, responda 200e ignore o evento. Nunca confirme um pedido apenas pelo valor.

// Exemplo em Node.js: IDs das cobranças criadas por este sistema.const minhasCobrancas = new Set(["pedido-123", "pedido-456"]);const eventosProcessados = new Set();
function receberPix(req, res) {  const eventoId = req.headers["x-elix-event-id"];  const conciliacaoId = req.body.QRCodeInfos?.ConciliationId;
  if (eventosProcessados.has(eventoId) || !minhasCobrancas.has(conciliacaoId)) {    return res.sendStatus(200); // Repetido ou de outro sistema: ignorar.  }
  // Confirme também os demais dados da cobrança antes de dar baixa.  eventosProcessados.add(eventoId);  return res.sendStatus(200);}

// Exemplo em Node.js: IDs das cobranças criadas por este sistema.const minhasCobrancas = new Set(["pedido-123", "pedido-456"]);const eventosProcessados = new Set();
function receberPix(req, res) {  const eventoId = req.headers["x-elix-event-id"];  const conciliacaoId = req.body.QRCodeInfos?.ConciliationId;
  if (eventosProcessados.has(eventoId) || !minhasCobrancas.has(conciliacaoId)) {    return res.sendStatus(200); // Repetido ou de outro sistema: ignorar.  }
  // Confirme também os demais dados da cobrança antes de dar baixa.  eventosProcessados.add(eventoId);  return res.sendStatus(200);}

Boas práticas

• Use uma URL HTTPS pública e dedicada para os eventos da Elix.
• Processe notificações de forma idempotente para evitar atualizações duplicadas.
• Nunca registre a Secret Key em logs nem a exponha no frontend.