Cria webhook(s) na chave Pix (não atualiza existentes). Um registro por valor em eventos. Máximo 3 webhooks ativos por combinação chave+evento (HTTP 422 se o limite for atingido). Eventos: recebimento, pagamento, pagamento-falha, devolucao. Após o evento, a API envia POST na webhookUrl (schema PixWebhookNotificacao) para todas as URLs daquele evento. Timeout 15 s, até 3 retentativas.
Define o formato dos dados enviados. Deve ser application/json
stringDefine o formato esperado na resposta. Deve ser application/json
stringToken de acesso no formato Bearer {access_token} para autenticação
stringChave Pix para cadastrar o webhook
stringParâmetros do Corpo da Requisição (Body)
| Nome | Obrigatório | Tipo | Descrição |
|---|---|---|---|
webhookUrl | Sim | String | URL para receber notificações de eventos relacionados à chave Pix. |
eventos | Sim | Array | Eventos Pix: "recebimento" (cash-in) ou "pagamento" (cash-out). |
autorizacao.tipo | Sim | String | Tipo de autorização (por exemplo, "none" para não exigir autenticação). |
autorizacao.valor | Sim | String | Valor para autorização (ou "none" se não exigir autenticação). |
| Nome | Tipo | Descrição |
|---|---|---|
webhooks | Array | Lista de webhooks registrados. |
webhooks.chave | String | Chave Pix vinculada ao webhook. |
webhooks.webhookUrl | String | URL configurada para receber notificações. |
webhooks.evento | String | Evento monitorado: recebimento ou pagamento. |
webhooks.criacao | String | Data e hora de criação do webhook (formato ISO 8601). |
correlationId | String | Identificador único da requisição para rastreabilidade. |
currentPage | Inteiro | Página atual na paginação dos resultados. |
lastPage | Inteiro | Número da última página disponível. |
perPage | Inteiro | Número de itens por página. |
from | Inteiro | Primeiro item exibido na página atual. |
to | Inteiro | Último item exibido na página atual. |
total | Inteiro | Total de itens disponíveis. |
path | String | URL base para consulta do recurso. |
firstPageUrl | String | URL para a primeira página de resultados. |
prevPageUrl | String | URL para a página anterior (ou null se não houver). |
nextPageUrl | String | URL para a próxima página (ou null se não houver). |
| Código | Significado | Descrição |
|---|---|---|
| 200 | OK | Webhook criado ou atualizado com sucesso. |
| 400 | Bad Request | Parâmetros inválidos ou faltando na requisição. |
| 401 | Unauthorized | Token de autenticação inválido ou expirado. |
| 500 | Internal Server Error | Erro interno no servidor. Contate o suporte se o problema persistir. |
Mesma estrutura JSON para recebimento e pagamento. A API envia POST na webhookUrl cadastrada (timeout 15 s, ate 3 retentativas a cada 300 s). Responda HTTP 2xx para encerrar retentativas.
Headers de entrega: X-REQUEST-ID (UUID por tentativa) e Authorization (quando configurado no cadastro).
Responsabilidade do integrador: idempotência por endToEndId (ou txid + endToEndId) e validação de status e demais campos antes de operacionalizar (baixa de cobrança, confirmação de pagamento).
Schema OpenAPI: #/components/schemas/PixWebhookNotificacao. Exemplos no callback Entrega na webhookUrl do PUT e em put-api-v2-cobranca-webhooks-chave-examples.
Guias: recebimento · pagamento.
Pagador e recebedor no payload
| Papel | Significado | Campos |
|---|---|---|
| Pagador | Quem enviou / debitou o Pix | nomePagador, cpfPagador, cnpjPagador, bancoPagador |
| Recebedor | Quem recebeu / creditou o Pix | nomeRecebedor, cpfRecebedor, cnpjRecebedor, bancoRecebedor, chave |
recebimento: integrador é o recebedor (crédito no QR).pagamento: integrador é o pagador (débito na conta). O campo chave do payload é do recebedor (destino), não confundir com {chave} da URL de cadastro.Recomendamos enfileirar o processamento e responder HTTP 2xx em seguida.
| Nome | Tipo | Descrição |
|---|---|---|
txid | String | null | Conciliação. null quando ausente |
tpIniciacao | Integer | recebimento: 2 QR estático, 3 QR dinâmico. pagamento: 1 ou -1 (ver guia de pagamento) |
valor | Number | String | Valor efetivado |
chave | String | null | Chave Pix do recebedor. recebimento: mesma do QR. pagamento: destino (ou null se manual) |
horario | String | Data/hora ISO 8601 |
status | String | Sempre "EFETIVADO" |
endToEndId | String | Identificador fim a fim |
infoPagador | Array | Reservado. Sempre [] |
bancoPagador | Object | Instituição do pagador |
bancoPagador.ispb | String | Integer | ISPB do pagador |
bancoPagador.nome | String | null | Nome da instituição do pagador |
nomePagador | String | Nome de quem pagou |
cpfPagador | String | null | CPF do pagador (PF) |
cnpjPagador | String | null | CNPJ do pagador (PJ) |
bancoRecebedor | Object | Instituição do recebedor |
bancoRecebedor.ispb | String | Integer | null | ISPB do recebedor |
bancoRecebedor.nome | String | null | Nome da instituição do recebedor |
nomeRecebedor | String | Nome de quem recebeu |
cpfRecebedor | String | null | CPF do recebedor (PF) |
cnpjRecebedor | String | null | CNPJ do recebedor (PJ) |
devolucoes | Array | Object | [] em recebimento/pagamento normais. Objeto preenchido em devolução |
motivo | String | null | Código em devolução (ex. MD06). null nos demais casos |
"recebimento" (guia) e "pagamento" (guia).DICA: O processamento de webhook pode ser feito com gestão de filas para tornar us aaplicação escalável.
curl --location --request PUT 'https://api-h.nuvende.com.br/api/v2/cobranca/webhooks/{{ chave }}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{ access_token }}' \
--data '{
"webhookUrl": "https://integrador.exemplo.com.br/pix/recebimento",
"eventos": [
"recebimento"
],
"autorizacao": {
"tipo": "none",
"valor": "none"
}
}'
const axios = require("axios");
const data = {
webhookUrl: "https://integrador.exemplo.com.br/pix/recebimento",
eventos: ["recebimento"],
autorizacao: {
tipo: "none",
valor: "none",
},
};
const config = {
method: "put",
url: "https://api-h.nuvende.com.br/api/v2/cobranca/webhooks/{{ chave }}",
headers: {
"Content-Type": "application/json",
Accept: "application/json",
Authorization: "Bearer {{ access_token }}",
},
data: data,
};
axios(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});
import requests
import json
url = "https://api-h.nuvende.com.br/api/v2/cobranca/webhooks/{{ chave }}"
payload = {
"webhookUrl": "https://integrador.exemplo.com.br/pix/recebimento",
"eventos": ["recebimento"],
"autorizacao": {
"tipo": "none",
"valor": "none"
}
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer {{ access_token }}'
}
response = requests.put(url, headers=headers, data=json.dumps(payload))
print(response.text)
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api-h.nuvende.com.br/api/v2/cobranca/webhooks/{{ chave }}',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_POSTFIELDS => json_encode(array(
'webhookUrl' => 'https://integrador.exemplo.com.br/pix/recebimento',
'eventos' => array('recebimento'),
'autorizacao' => array(
'tipo' => 'none',
'valor' => 'none'
)
)),
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'Accept: application/json',
'Authorization: Bearer {{ access_token }}'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>
{
"webhooks": [
{
"chave": "e3fe4462-4c8e-42c1-8360-b41b404ae557",
"webhookUrl": "https://integrador.exemplo.com.br/pix/recebimento",
"evento": "recebimento",
"criacao": "2024-12-26T15:18:12.000000Z"
}
],
"correlationId": "f2ce6ef2-dfea-4fd7-9a3b-4cc9af2bc9fb",
"currentPage": 1,
"lastPage": 1,
"perPage": 10,
"from": 1,
"to": 1,
"total": 1
}
{
"txid": "7978c0c97ea847e78e8849634473c1f1",
"tpIniciacao": 3,
"valor": 150.85,
"chave": "[email protected]",
"horario": "2020-01-23T22:08:10.012Z",
"status": "EFETIVADO",
"endToEndId": "E0435879820200123221500000000001",
"infoPagador": [],
"bancoPagador": {
"ispb": "12345678",
"nome": "Banco Pagador Exemplo"
},
"nomePagador": "Maria Pagadora Exemplo",
"cpfPagador": "11144477735",
"cnpjPagador": null,
"bancoRecebedor": {
"ispb": "87654321",
"nome": "Banco Recebedor Exemplo"
},
"nomeRecebedor": "Loja Exemplo LTDA",
"cpfRecebedor": null,
"cnpjRecebedor": "43587980000107",
"devolucoes": [],
"motivo": null
}
{
"txid": null,
"tpIniciacao": 1,
"valor": "0.5",
"chave": "[email protected]",
"horario": "2026-07-09T14:36:52.134Z",
"status": "EFETIVADO",
"endToEndId": "E38297374202607091436QRJZZCLVR3H",
"infoPagador": [],
"bancoPagador": {
"ispb": "12345678",
"nome": "Instituicao Exemplo"
},
"nomePagador": "Maria Pagadora Exemplo",
"cpfPagador": "11144477735",
"cnpjPagador": null,
"bancoRecebedor": {
"ispb": "12345678",
"nome": "Instituicao Exemplo"
},
"nomeRecebedor": "Maria Recebedora Exemplo",
"cpfRecebedor": "52998224725",
"cnpjRecebedor": null,
"devolucoes": [],
"motivo": null
}