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
- Cadastre um ou mais webhooks via
POST /v1/webhooks(URL HTTPS + secret). - 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
| Header | Valor |
|---|---|
Content-Type | application/json |
Authorization | O secret que você informou ao cadastrar o webhook (enviamos esse valor literalmente no header Authorization) |
User-Agent | OpenFinance-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
-
Verifique o header
Authorization
O valor deve ser exatamente o mesmosecretque você configurou ao criar o webhook. Se for diferente, rejeite a requisição (ex.: responda com401 Unauthorized). -
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)
- Expor um endpoint HTTPS que aceita POST.
- Cadastrar essa URL em
POST /v1/webhookscom umsecretforte. - Em cada POST recebido:
- Validar
Authorization=== seusecret. - Parsear o JSON e identificar
eventedata. - 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.
- Validar
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.

