Webhooks

Sistema de comunicação de eventos da Equals para sua aplicação.

---

Disponibilidade: Apenas em Produção

IMPORTANTE: A funcionalidade de Webhooks está disponível EXCLUSIVAMENTE no ambiente de Produção.

Ambiente	Webhooks Disponíveis?
Sandbox (Homologação)	Não
Produção	Sim

Para testes no Sandbox:

• Utilize Polling (consulta ativa via GET /retornos?id={ID}) para acompanhar o status
• Lembre-se que no Sandbox o status é fixo como EM_PROCESSAMENTO e os dados já estão disponíveis imediatamente
• A lógica de Webhook que você desenvolver deverá ser testada apenas em Produção

---

Por que Webhooks apenas em Produção?

Os Webhooks exigem:

• Endpoints HTTPS públicos e acessíveis
• Configuração de segurança HMAC
• Infraestrutura de entrega garantida

Durante a fase de homologação (Sandbox), você pode:

1. Desenvolver e testar toda a lógica de consumo da API REST
2. Simular o recebimento de Webhooks localmente (usando ferramentas de sua preferência)
3. Configurar os Webhooks no ambiente de Produção quando estiver pronto

---

Tipo de Evento

Código	Descrição	Payload	Ambiente
1	Notificação de geração de arquivo de retorno	{ "id": idMovFinan, "pagina": YYY }	Produção apenas

Estrutura da Notificação

Headers

{
  "x-request-id": "a8287517-d1b8-4c3f-99dd-2282e8eff74c",
  "x-signature": "sha256=dH+VKeC42RReK+8pEVaKwlV71GnZ/adLquUEWCcpUhs=",
  "x-signature-algorithm": "HMAC-SHA256",
  "x-signature-version": "v1",
  "x-timestamp": "1763994318"
}

Body

{
  "version": "1.0",
  "requestId": "a8287517-d1b8-4c3f-99dd-2282e8eff74c",
  "payload": {
    "evento": {
      "code": 1,
      "descricao": "Notificação de geração de arquivo de retorno solicitado pelo cliente"
    },
    "data": {
      "id": 7000000001110834,
      "pagina": 1
    }
  }
}

Validação HMAC

A assinatura é gerada com HMAC-SHA256 usando seu Secret HMAC sobre o corpo bruto da requisição.

const crypto = require('crypto');

function validateSignature(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('base64');
  
  return signature === `sha256=${expected}`;
}

Endpoints de Gestão

Operação	Endpoint
Criar	POST /webhooks
Listar	GET /webhooks
Atualizar	PUT /webhooks/{id}
Excluir	DELETE /webhooks/{id}

Payload de Criação

{
  "idTipoEvento": 1,
  "endpoint": "https://seu-sistema.com/webhook",
  "hmac": "seu_secret_hmac",
  "headersExtra": { "codigo_interno": "99999" },
  "flagAtivo": 1
}

[!IMPORTANT] Sua aplicação deve responder com 200 OK imediatamente após receber a notificação.