Webhook — Recebimento

Notificação HTTP que o integrador recebedor recebe quando alguém paga um QR Code Pix emitido por ele (cash-in confirmado).

Evento recebimento (Recebimento de Pix). Para cash-out (efetivado ou falha), veja Webhook de pagamento.

Pagador e recebedor

No evento recebimento, {chave} na URL do cadastro e chave no payload referem-se à mesma chave Pix do recebedor (a do QR).

Cadastro

Registrar o webhook na chave Pix vinculada ao QR (mesma chave embutida no BR Code).

{
  "webhookUrl": "https://integrador.exemplo.com.br/pix/recebimento",
  "eventos": ["recebimento"]
}

O PUT somente cria. Para alterar URL ou autorização, use PATCH /{id} com o id retornado no GET/PUT. Para remover, use DELETE /{id}.

Contraste com pagamento: os eventos pagamento e pagamento-falha aceitam cadastro em qualquer chave da conta pagadora. Ver Webhook de pagamento.

Autorização opcional (autorizacao.tipo + autorizacao.valor) — repassada no header Authorization de cada entrega.

curl --location --request PUT 'https://api-h.nuvende.com.br/api/v2/cobranca/webhooks/{{chave_pix}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
  "webhookUrl": "https://integrador.exemplo.com.br/pix/recebimento",
  "eventos": ["recebimento"]
}'

Scopes: webhooks.read / webhooks.write.

Quando dispara

Pagador paga QR Code
  → crédito Pix processado
  → POST na webhookUrl do integrador (evento recebimento)

Se houver vários webhooks recebimento na chave (até 3), todos recebem o mesmo payload. Sem webhook na chave → nenhuma requisição.

Identificação do QR no payload

Outros valores (ex.: iniciação manual ou por chave) usam o mesmo formato de payload; o foco desta página é o pagamento via QR.

Entrega HTTP

Headers

Payload

Corpo JSON enviado no POST. Estrutura alinhada ao webhook de pagamento, com campo reservado infoPagador: [] neste evento (pagamento / pagamento-falha usam infoRecebedor: []).

Exemplo — QR dinâmico pago

{
  "txid": "7978c0c97ea847e78e8849634473c1f1",
  "tpIniciacao": 3,
  "valor": 150.85,
  "chave": "[email protected]",
  "horario": "2020-01-23T22:08:10.012Z",
  "status": "EFETIVADO",
  "endToEndId": "E0435879820200123221500000000001",
  "infoPagador": [],
  "bancoPagador": {
    "ispb": "04358798",
    "nome": "Banco do Pagador S.A."
  },
  "nomePagador": "Fulano de Tal",
  "cpfPagador": "11111111111",
  "cnpjPagador": null,
  "bancoRecebedor": {
    "ispb": "38297374",
    "nome": "Nuvende IP S.A."
  },
  "nomeRecebedor": "Loja Exemplo LTDA",
  "cpfRecebedor": null,
  "cnpjRecebedor": "4358798000107",
  "devolucoes": [],
  "motivo": null
}

Exemplo — QR estático pago

{
  "txid": null,
  "tpIniciacao": 2,
  "valor": 49.90,
  "chave": "efca2b48-0d8a-4f10-9f07-26e6b5a1b921",
  "horario": "2026-07-08T15:30:00.000000Z",
  "status": "EFETIVADO",
  "endToEndId": "E382973742026070815500QR1234567890",
  "infoPagador": [],
  "bancoPagador": {
    "ispb": "00000000",
    "nome": "Banco Externo S.A."
  },
  "nomePagador": "Maria Pagadora",
  "cpfPagador": "98765432100",
  "cnpjPagador": null,
  "bancoRecebedor": {
    "ispb": "38297374",
    "nome": "Nuvende IP S.A."
  },
  "nomeRecebedor": "Maria Souza Exemplo",
  "cpfRecebedor": "52998224725",
  "cnpjRecebedor": null,
  "devolucoes": [],
  "motivo": null
}

Referência de campos

Regras de negócio

Conciliação

• QR dinâmico: use txid para correlacionar com a cobrança criada via API.
• QR estático sem txid: concilie por endToEndId + valor + horario.

Chave do webhook

Roteamento pela chave Pix do QR, não pela conta. Cadastre o webhook na mesma chave usada ao gerar o QR. Com várias chaves, cada uma precisa de cadastro próprio.

Idempotência no integrador (receptor)

A Nuvende envia até 3 retentativas (intervalo de 300 s) quando não recebe HTTP 2xx em até 15 s. O mesmo evento de negócio pode chegar mais de uma vez — com o mesmo payload e novo X-REQUEST-ID por tentativa.

Obrigação do integrador: tratar o endpoint de webhook como idempotente no seu sistema, para evitar efeitos operacionais duplicados (baixa em dobro da cobrança, crédito repetido no saldo interno, reenvio de e-mail/NF, fila processada duas vezes). Validar status (ex.: EFETIVADO) e demais campos do payload antes de operacionalizar na aplicação; não baixe cobrança nem credite saldo interno sem conferir o status enviado.

Práticas recomendadas:

1. Persistir antes de responder 2xx — grave a chave de idempotência (ex.: endToEndId) em transação atômica; só então retorne HTTP 2xx.
2. Repetição = no-op — se a chave já foi processada com sucesso, responda 2xx sem reexecutar regras de negócio (não retorne 4xx por “duplicado”).
3. Processamento assíncrono — se usar fila, enfileire com a mesma chave; consumidores devem deduplicar.
4. Concorrência — duas requisições simultâneas com o mesmo endToEndId devem resultar em um único efeito (lock otimista, INSERT com constraint única ou equivalente).

Trate endToEndId como identificador único do evento. Responda 2xx o mais rápido possível após garantir idempotência; timeout ou status ≥ 400 geram nova tentativa.

O que este webhook não cobre

Resposta esperada

Qualquer status 2xx. Corpo vazio ou {} — ambos aceitos.

HTTP/1.1 200 OK

Relacionado

• Criar QR Code
• Consultar QR Code
• Pagamentos (cash-out)
• Webhook de pagamento (cash-out efetivado e falha)