PUT/api/v2/cobranca/webhooks/{chave}

Criar

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.

Parâmetros

Content-TypeObrigatório
header

Define o formato dos dados enviados. Deve ser application/json

Tipo:string
AcceptObrigatório
header

Define o formato esperado na resposta. Deve ser application/json

Tipo:string
AuthorizationObrigatório
header

Token de acesso no formato Bearer {access_token} para autenticação

Tipo:string
chaveObrigatório
path

Chave Pix para cadastrar o webhook

Tipo:string

Parâmetros do Corpo da Requisição (Body)

NomeObrigatórioTipoDescrição
webhookUrlSimStringURL para receber notificações de eventos relacionados à chave Pix.
eventosSimArrayEventos Pix: "recebimento" (cash-in) ou "pagamento" (cash-out).
autorizacao.tipoSimStringTipo de autorização (por exemplo, "none" para não exigir autenticação).
autorizacao.valorSimStringValor para autorização (ou "none" se não exigir autenticação).

Descrição dos Campos da Resposta

NomeTipoDescrição
webhooksArrayLista de webhooks registrados.
webhooks.chaveStringChave Pix vinculada ao webhook.
webhooks.webhookUrlStringURL configurada para receber notificações.
webhooks.eventoStringEvento monitorado: recebimento ou pagamento.
webhooks.criacaoStringData e hora de criação do webhook (formato ISO 8601).
correlationIdStringIdentificador único da requisição para rastreabilidade.
currentPageInteiroPágina atual na paginação dos resultados.
lastPageInteiroNúmero da última página disponível.
perPageInteiroNúmero de itens por página.
fromInteiroPrimeiro item exibido na página atual.
toInteiroÚltimo item exibido na página atual.
totalInteiroTotal de itens disponíveis.
pathStringURL base para consulta do recurso.
firstPageUrlStringURL para a primeira página de resultados.
prevPageUrlStringURL para a página anterior (ou null se não houver).
nextPageUrlStringURL para a próxima página (ou null se não houver).

Códigos de Resposta

CódigoSignificadoDescrição
200OKWebhook criado ou atualizado com sucesso.
400Bad RequestParâmetros inválidos ou faltando na requisição.
401UnauthorizedToken de autenticação inválido ou expirado.
500Internal Server ErrorErro interno no servidor. Contate o suporte se o problema persistir.

Payload do webhook disparado (POST na webhookUrl)

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

PapelSignificadoCampos
PagadorQuem enviou / debitou o PixnomePagador, cpfPagador, cnpjPagador, bancoPagador
RecebedorQuem recebeu / creditou o PixnomeRecebedor, cpfRecebedor, cnpjRecebedor, bancoRecebedor, chave
  • Evento recebimento: integrador é o recebedor (crédito no QR).
  • Evento 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.

NomeTipoDescrição
txidString | nullConciliação. null quando ausente
tpIniciacaoIntegerrecebimento: 2 QR estático, 3 QR dinâmico. pagamento: 1 ou -1 (ver guia de pagamento)
valorNumber | StringValor efetivado
chaveString | nullChave Pix do recebedor. recebimento: mesma do QR. pagamento: destino (ou null se manual)
horarioStringData/hora ISO 8601
statusStringSempre "EFETIVADO"
endToEndIdStringIdentificador fim a fim
infoPagadorArrayReservado. Sempre []
bancoPagadorObjectInstituição do pagador
bancoPagador.ispbString | IntegerISPB do pagador
bancoPagador.nomeString | nullNome da instituição do pagador
nomePagadorStringNome de quem pagou
cpfPagadorString | nullCPF do pagador (PF)
cnpjPagadorString | nullCNPJ do pagador (PJ)
bancoRecebedorObjectInstituição do recebedor
bancoRecebedor.ispbString | Integer | nullISPB do recebedor
bancoRecebedor.nomeString | nullNome da instituição do recebedor
nomeRecebedorStringNome de quem recebeu
cpfRecebedorString | nullCPF do recebedor (PF)
cnpjRecebedorString | nullCNPJ do recebedor (PJ)
devolucoesArray | Object[] em recebimento/pagamento normais. Objeto preenchido em devolução
motivoString | nullCódigo em devolução (ex. MD06). null nos demais casos

Notas Importantes

  • Caso já exista um webhook para a chave fornecida, ele será atualizado com os novos parâmetros.
  • Eventos Pix: "recebimento" (guia) e "pagamento" (guia).
  • Em casos de falha no envio, o sistema poderá tentar reenviar a notificação em um intervalo de 5 minutos por até três vezes.
  • O timeout de envio é de 15 segundos.
  • Para testar o recebimento, ferramentas como RequestBin, Postman ou Webhook.site podem ser utilizadas.

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
}