Openi DeveloperDeveloper
Webhooks

Como receber webhooks

Fluxo exato para configurar seu endpoint e processar notificações da API de forma segura.

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

Implemente webhooks com IA

Implemente o recebimento de webhooks da Openi Open Finance neste projeto.

## Contexto
- Base URL: https://of.openi.com.br/v1 (os caminhos abaixo são relativos a ela). Header `Authorization: Bearer $OPENI_API_KEY`, lido da variável de ambiente `OPENI_API_KEY`, só no backend.
- Doc: https://developer.openi.com.br/docs/openfinance/webhooks/receiving-webhooks.md e https://developer.openi.com.br/docs/openfinance/webhooks/events/overview.md

## Como a Openi envia
- `POST` com `Content-Type: application/json` e `User-Agent: OpenFinance-Webhook/1.0`.
- O header `Authorization` traz literalmente o `secret` cadastrado no webhook.
- Corpo: `{ "event": "NOME_DO_EVENTO", "data": { ... } }`.
- Qualquer resposta fora de 2xx, ou sem resposta em 5 s, gera retentativas (5 min, 30 min, 1 h, 3 h, 8 h, 12 h).

## Tarefa
1. No seu app, crie a rota `POST /webhooks/openi`. Compare o header `Authorization` com `OPENI_WEBHOOK_SECRET` em tempo constante; se diferente, responda 401.
2. Responda 200 assim que o evento estiver persistido ou enfileirado; processe em background.
3. Processe de forma idempotente, porque o mesmo evento pode chegar mais de uma vez: aplique o estado recebido com upsert (item por `itemId`; transações pelos `transactionIds`; investimentos pelos `investmentIds`) em vez de descartar eventos já vistos. O mesmo `event` + `itemId` + `status` se repete legitimamente a cada nova sincronização, e a mesma transação pode ser atualizada mais de uma vez.
4. Trate `ITEM_UPDATED` / `ITEM_LOGIN_SUCCEEDED` (status `synced`: buscar contas), `ITEM_ERROR` (marcar a conexão com erro), `TRANSACTIONS_CREATED` (buscar transações novas) e `TRANSACTIONS_DELETED` (apagar da base os `transactionIds` recebidos; a API não os retorna mais). Responda 2xx também aos demais eventos (ex.: `INVESTMENTS_UPDATED`), mesmo sem tratá-los, para não gerar retentativas.
5. Cadastre a URL com `POST /webhooks` e `{ "url": "https://...", "secret": "<OPENI_WEBHOOK_SECRET>" }`. Em desenvolvimento, use um túnel HTTPS.

## Critério de pronto
Conecte um item de sandbox com o CPF `111.444.777-35` e me mostre os eventos recebidos, em ordem.

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

HeaderValor
Content-Typeapplication/json
AuthorizationO secret que você informou ao cadastrar o webhook (enviamos esse valor literalmente no header Authorization)
User-AgentOpenFinance-Webhook/1.0

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, TRANSACTIONS_DELETED
  • Investimentos: INVESTMENTS_UPDATED

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

On this page