---
title: 3.0. Visão Geral
url: https://docs.vehub.com.br/API/VeFlow%20-%20Cart%C3%A3o%20de%20cr%C3%A9dito/3.%20Notifica%C3%A7%C3%B5es%20-%20WebHook/3.0.%20Vis%C3%A3o%20Geral/
---
# 3.0. Visão Geral

## 🧾 Descrição

A plataforma **VeFlow** envia **notificações via WebHook** para informar o cliente sobre eventos que acontecem de forma **assíncrona** no fluxo de recebíveis de cartão: a chegada das URs consultadas nas registradoras, a evolução do contrato e o resultado da conciliação de cada UR.

Todas as notificações são entregues por uma requisição **`POST`** para a **URL de callback** informada pelo cliente na implantação. O corpo é sempre JSON em UTF-8, e o campo `tipoNotificacao`, presente na raiz do payload, identifica qual notificação chegou — use-o para rotear o processamento.

Uma notificação pode ser **reenviada** (por retentativa ou porque a posição do recurso mudou de novo), sempre carregando a **última posição conhecida**. Por isso o endpoint do cliente **precisa ser idempotente**.

---

## 🔔 Tipos de Notificação

| tipoNotificacao | Notificação | Página | Quando é disparada |
| --------------- | ----------- | ------ | ------------------ |
| `1` | Listagem de URs | [3.1. Listagem de URs](3.1.%20Listagem%20de%20URs.md) | A consulta da agenda foi concluída e as URs recebidas da registradora já estão disponíveis para uso |
| `2` | Atualizações do contrato | [3.2. Atualizações do contrato](3.2.%20Atualizações%20do%20contrato.md) | O contrato mudou de status, teve URs incluídas/removidas ou teve seus totais recalculados |
| `3` | Atualizações da UR | [3.3. Atualizações da UR](3.3.%20Atualizações%20da%20UR.md) | A conciliação identificou mudança de valor, de prioridade ou liquidação de uma UR do contrato |

> Todas as notificações chegam na **mesma URL de callback**. Não existe URL por tipo: o roteamento é responsabilidade do cliente, a partir de `tipoNotificacao`.

---

## 📦 Envelope Padrão

O payload não tem envelope aninhado: `tipoNotificacao` fica na raiz, ao lado dos blocos específicos daquele tipo.

```json
{
  "tipoNotificacao": 1,
  "...": "blocos específicos do tipo de notificação"
}
```

| Campo | Tipo | Descrição |
| ----- | ---- | --------- |
| tipoNotificacao | integer | Identifica o tipo da notificação (`1`, `2` ou `3`). Sempre presente na raiz do payload. |

**Convenções dos payloads**

* Nomes de campos em **camelCase**.
* Datas no formato `YYYY-MM-DD`; data e hora no formato ISO 8601.
* Valores monetários como `number` com 2 casas decimais.
* O array `titulos` transporta as **URs** envolvidas na notificação; o endpoint deve estar apto a processar **várias URs por envio**.

---

## 📨 Headers do Disparo

Toda requisição enviada pela plataforma inclui:

| Header | Exemplo | Descrição |
| ------ | ------- | --------- |
| `Content-Type` | `application/json; charset=utf-8` | Sempre JSON em UTF-8 |
| `Authorization` | `Bearer {seu_token}` | Credencial do callback, conforme combinado na implantação |
| `Idempotency-Key` | `9f2c1b7e-5d84-4f3a-9c21-77bde1a4c5f0` | GUID único do disparo. **Use para deduplicação.** Retentativas do mesmo disparo repetem este valor. |

```http
POST /webhook/veflow HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: Bearer {seu_token}
Idempotency-Key: 9f2c1b7e-5d84-4f3a-9c21-77bde1a4c5f0

{
  "tipoNotificacao": 2,
  "...": "..."
}
```

---

## 🔐 Autenticação do Callback

A URL de callback e a forma de autenticação são definidas junto ao time de implantação. Regras:

* A URL precisa ser **HTTPS**. URLs em `http://` não são aceitas.
* A plataforma envia a credencial acordada no header `Authorization` (padrão: **Bearer token fixo**).
* O cliente **deve validar** o header `Authorization` em toda requisição e responder `401` quando a credencial não conferir.
* A rotação da credencial e a alteração da URL de callback são solicitadas ao time de implantação — contato: **contato@vertrau.capital**.

> Não use a credencial da API VeFlow como credencial do callback: são segredos distintos e com ciclos de vida independentes.

---

## ✅ Como o Endpoint do Cliente Deve Responder

| Resposta do cliente | Interpretação da plataforma |
| ------------------- | --------------------------- |
| `200 OK` ou `204 No Content` | Entrega confirmada. O disparo é encerrado. |
| `408`, `429` ou `5xx` | Falha transitória. O disparo entra em **retentativa** (ver abaixo). |
| Timeout, DNS, conexão recusada | Falha transitória. O disparo entra em **retentativa**. |
| Demais `4xx` (`400`, `401`, `403`, `404`, `422`) | Falha definitiva. **Não há retentativa** — o disparo é registrado como falho. |
| `3xx` (redirect) | Tratado como falha. A plataforma **não segue redirecionamentos**. |

Regras de implementação:

* Responda `2xx` **assim que receber** a mensagem, idealmente em **menos de 5 segundos**, e processe o conteúdo de forma assíncrona (fila interna). Processamento longo dentro do request causa timeout e retentativa desnecessária.
* O corpo da resposta é **ignorado** pela plataforma. Só o status HTTP importa.
* Não responda `2xx` para descartar mensagem que você não conseguiu processar: nesse caso deixe a plataforma retentar (`5xx`).

---

## 🔁 Retentativa e Backoff

A entrega é considerada bem-sucedida quando o cliente responde **`2xx`**. Em falha transitória, há **retentativa com backoff exponencial e jitter**, repetindo o mesmo `Idempotency-Key`:

| Tentativa | Delay aproximado |
| --------- | ---------------- |
| 1 | imediato |
| 2 | ~1s + jitter |
| 3 | ~2s + jitter |
| 4 | ~4s + jitter |
| 5 | ~8s + jitter |

Após **5 tentativas** sem sucesso, o disparo é registrado como falho e **não é mais retentado automaticamente**. A posição atual do recurso continua disponível por consulta ativa:

* Agenda e URs: [4.3. Detalhes da agenda](../4.%20Agenda%20de%20recebíveis/v1.1/4.3.%20Detalhes%20da%20agenda.md) e [4.4. Listar URs da agenda](../4.%20Agenda%20de%20recebíveis/v1.1/4.4.%20Listar%20URs%20da%20agenda.md).
* Contrato: [5.3. Detalhes do contrato](../5.%20Contrato%20de%20recebíveis/v1.1/5.3.%20Detalhes%20do%20contrato.md).
* Conciliação: [7.1. Posição do contrato](../7.%20Conciliação/v1.1/7.1.%20Posição%20do%20contrato.md).

---

## 🪞 Deduplicação por Chave de Idempotência

Como uma retentativa pode entregar a **mesma** notificação mais de uma vez, o cliente **deve deduplicar** pelo header `Idempotency-Key`.

Padrão recomendado:

1. Ao receber a notificação, persista o `Idempotency-Key` em uma tabela com **unique constraint**.
2. Se o `INSERT` falhar por violação de unicidade, responda **`200 OK`** sem reprocessar.
3. Caso contrário, enfileire o processamento e responda **`200 OK`**.

---

## ♻️ Por Que o Endpoint Precisa Ser Idempotente

Deduplicar pelo `Idempotency-Key` resolve a **retentativa**, mas não é o único motivo de reenvio. A mesma notificação é **reenviada com um novo disparo** sempre que a posição do recurso muda de novo — por exemplo, um contrato que passa por `Registrando`, `Aguardando liquidação`, `Em liquidação` e `Liquidado` gera quatro notificações de `tipoNotificacao = 2` para o mesmo `contrato.identificador`.

Portanto:

* Trate cada notificação como **"última posição conhecida"**, e não como um delta a ser somado ao seu estado local. Sobrescreva, não acumule.
* **Não presuma ordem de entrega.** Duas notificações do mesmo recurso podem chegar fora de ordem. Compare com o estado que você já tem e descarte o retrocesso, ou reconsulte o recurso pelo endpoint de detalhes.
* Reprocessar a mesma posição **não pode** gerar efeito colateral duplicado (lançamento contábil repetido, e-mail reenviado, baixa duplicada).

---

## 🕒 Observações

* As notificações são **assíncronas**: não existe garantia de que cheguem dentro da mesma requisição HTTP que originou o processamento.
* A consulta da agenda é processada **apenas entre 09:00 e 18:00 em dias úteis**. Solicitações recebidas fora dessa janela são agendadas para o próximo dia útil, e a notificação `tipoNotificacao = 1` só é disparada quando o processamento efetivamente ocorre — ver [4.1. Solicitar agenda](../4.%20Agenda%20de%20recebíveis/v1.1/4.1.%20Solicitar%20agenda.md).
* A conciliação roda em vários ciclos ao longo do dia; o evento de UR não liquidada é apurado somente no **último processamento do dia (19h)** — ver [3.3. Atualizações da UR](3.3.%20Atualizações%20da%20UR.md).
* Credenciais da API, headers obrigatórios e ambientes: [1.1. Primeiros Passos](../1.%20Início/1.1.%20Primeiros%20Passos.md).