Como receber webhooks

Este guia descreve o fluxo exato para receber webhooks da Open Finance: desde o cadastro até a validação e o tratamento de retentativas.

Ordem recomendada: cadastre o webhook antes de criar itens

1. Cadastre um ou mais webhooks via POST /v1/webhooks (URL HTTPS + secret).
2. Depois crie itens com POST /v1/items.

Assim, você passa a receber eventos desde o primeiro momento em que um item muda de status (por exemplo, ITEM_CREATED, ITEM_UPDATED, ITEM_LOGIN_SUCCEEDED, TRANSACTIONS_CREATED), sem depender apenas de polling em Buscar Item.

O que a API envia para o seu endpoint

Para cada evento (mudança de status de item, novas transações, etc.), a API faz uma requisição HTTP POST para a URL que você cadastrou, com o seguinte formato.

Cabeçalhos

Corpo (JSON)

{
  "event": "NOME_DO_EVENTO",
  "data": { ... }
}

• event: nome do evento (ex.: ITEM_CREATED, ITEM_UPDATED, TRANSACTIONS_CREATED). Lista completa em Eventos.
• data: payload específico do evento (ex.: itemId, status, accountId).

Como validar que a requisição é da Open Finance

1. Verifique o header Authorization
   O valor deve ser exatamente o mesmo secret que você configurou ao criar o webhook. Se for diferente, rejeite a requisição (ex.: responda com 401 Unauthorized).

2. Use HTTPS na URL do webhook
   A API só aceita URLs HTTPS no cadastro; isso protege o conteúdo em trânsito.

Recomendação: no seu backend, armazene o secret de forma segura (variável de ambiente ou secrets manager) e compare com o header Authorization em toda requisição POST recebida no endpoint do webhook.

O que seu endpoint deve retornar

• Resposta com status HTTP 2xx (200–299)
  A API considera entrega concluída com sucesso. Não fazemos retentativa para essas respostas.

• Resposta com status ≥ 400
  A API considera falha e agenda retentativas automáticas (ver abaixo). Evite retornar 2xx se ainda não processou o evento com sucesso (por exemplo, se falhou ao gravar no banco).

Recomendação: processe o body (parse do JSON, validação do event e do data) e só então responda com 200 (ou outro 2xx). Em caso de erro interno, responda com 5xx para que o evento seja reenviado.

Timeout e retentativas

• Timeout da requisição: a API espera resposta do seu endpoint em até 5 segundos (primeira tentativa) e 10 segundos (retentativas). Se o seu processamento for demorado, considere responder 200 rapidamente e processar em background (fila/job).

• Retentativas: se a API receber status ≥ 400 ou sofrer timeout/erro de rede, o mesmo evento é reenviado em intervalos crescentes:

  • 5 min, 30 min, 1 h, 3 h, 8 h, 12 h (até 6 tentativas).
  • Após esgotar as tentativas, o evento não é mais reenviado.

Por isso é importante que seu endpoint seja idempotente: receber o mesmo evento mais de uma vez não deve gerar duplicidade de efeitos (ex.: não criar o mesmo registro duas vezes). Use o event + dados do data (ex.: itemId, transactionIds) para deduplicar.

Fluxo resumido (seu lado)

1. Expor um endpoint HTTPS que aceita POST.
2. Cadastrar essa URL em POST /v1/webhooks com um secret forte.
3. Em cada POST recebido:
   • Validar Authorization === seu secret.
   • Parsear o JSON e identificar event e data.
   • Processar de forma idempotente (e, se quiser, assíncrona).
   • Retornar 2xx somente após sucesso (ou após enfileirar com sucesso); 4xx/5xx em caso de falha para permitir retentativa.

Lista de eventos

Os eventos que você pode receber estão documentados em Eventos, com payload e exemplos para cada um:

• Itens: ITEM_CREATED, ITEM_UPDATED, ITEM_DELETED, ITEM_ERROR, ITEM_WAITING_USER_INPUT, ITEM_WAITING_USER_ACTION, ITEM_LOGIN_SUCCEEDED
• Transações: TRANSACTIONS_CREATED, TRANSACTIONS_UPDATED

Para o fluxo completo de conexão (incluindo quando cada evento aparece), veja Fluxo de conexão.