Webhooks

Configuração de webhooks

Cadastre endpoints HTTPS para receber, em tempo real, eventos de liquidação e devolução — sem precisar de polling.

Cadastrar webhook

POST/integration/v1/webhooks

Campos

Campo	Tipo	Descrição
eventType*	enum	Tipo de evento. Ver Catálogo de eventos.
endpointUrl*	uri (https)	URL HTTPS pública que receberá o POST do evento.
applicationId	string	Identificador livre da sua aplicação consumidora.
enabled	boolean	Habilita/desabilita a entrega (default true).
ref	uuid	Sua referência interna de configuração.

curl -X POST https://apiapp.dev.ideabank.com.br/integration/v1/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenantid: $TENANT_ID" -H "hostdevelop: apiapp.dev.ideabank.com.br" -H "Content-Type: application/json" \
  -d '{
    "eventType": "PIX_DYNAMIC_PAID",
    "endpointUrl": "https://minha-loja.com/webhooks/pix",
    "applicationId": "checkout-service",
    "enabled": true
  }'

Atualizar webhook

PUT/integration/v1/webhooks

Listar webhooks

GET/integration/v1/webhooks

{
  "data": [
    {
      "eventType": "PIX_DYNAMIC_PAID",
      "endpointUrl": "https://minha-loja.com/webhooks/pix",
      "applicationId": "checkout-service",
      "enabled": true
    }
  ],
  "results": 1
}

Para desativar uma entrega, use PUT com enabled: false — não há rota DELETE de webhooks.

Webhooks não exigem vínculo de conta

As rotas de webhook configuram a própria integração (por applicationId), não operam sobre uma conta — basta um token M2M válido, sem headers de conta.

Como sua aplicação recebe

O evento chega como um POST JSON. Responda rapidamente com HTTP 2xx:

app.post("/webhooks/pix", express.json(), async (req, res) => {
  const evt = req.body;
  // 1. Responda 2xx o mais rápido possível
  res.status(200).end();

  // 2. Enfileire o processamento (BullMQ, SQS, etc.) com idempotência por evt.id
  await queue.add("pix-event", evt, { jobId: evt.id });
});

Retries

Respostas fora de 2xx acionam retentativas com backoff exponencial.
Um mesmo evento pode chegar mais de uma vez — deduplique por id do evento.
Timeouts longos do seu lado degradam a fila. Devolva 2xx e processe em background.

Segurança do endpoint

Sempre HTTPS com certificado válido.
Se seu ambiente exigir, coordene lista de IPs de origem com o time Idea+Cash.
Assinatura HMAC-SHA256 do payload (header X-Idea-Signature) está no roadmap — ver Em breve.

Fonte de verdade

Webhook é notificação. Antes de faturar, liberar produto ou pagar seller, recupere o estado real consultando GET /integration/v1/pix/cob/{txId} ou GET /integration/v1/pix/transaction?endToEndId=.... A API de consulta é a fonte de verdade e permite reconciliar mesmo se um webhook falhar.

Ver: catálogo de eventos.