Acessar minha contaAbrir uma conta
POST/api/v2/baas/webhooks

Criar

Produto BaaS (titular). Requer Bearer JWT do login da conta e assinatura HMAC obrigatória. Scope: baas.webhooks.write. Guia: documentação técnica.

Parâmetros

AcceptObrigatório
header
Tipo:string
X-SignatureObrigatório
header

Assinatura HMAC-SHA256 da requisição (hex).

Tipo:string
X-TimestampObrigatório
header

Timestamp Unix (segundos, UTC) usado na assinatura.

Tipo:string
X-NonceObrigatório
header

Nonce único por requisição (anti-replay).

Tipo:string

Autenticação e headers

Requer Bearer token do login da conta e assinatura HMAC obrigatórios. Scope: baas.webhooks.write.

Envie X-Signature, X-Timestamp e X-Nonce em todo pedido assinado. Veja Assinatura HMAC.

HeaderObrigatórioDescrição
AuthorizationSimBearer {{access_token}}
AcceptSimapplication/json
X-SignatureSimAssinatura HMAC
X-TimestampSimTimestamp da assinatura
X-NonceSimNonce único por requisição

Corpo

CampoObrigatórioDescrição
urlSimURL HTTPS de callback
eventsSimArray com slugs (pix-received, pix-sent, etc.)
entityNãoFiltro por domínio: contracts, onboardings, pix-payments, accounts, key-managements, bankslip-payments
methodNãoPOST, PUT ou PATCH
statusNãoACTIVE, INACTIVE, PENDING

Códigos

CódigoDescrição
200OK
201Recurso criado
400Parâmetros inválidos
401Token ou HMAC inválido
403Scope ausente
404Não encontrado
422Validação ou regra de negócio
500Erro interno

Payload enviado ao integrador (POST na url)

Quando um evento de events[] dispara, a Nuvende faz POST na url cadastrada. Não é endpoint da API pública: é o JSON inbound que seu servidor deve receber.

CampoUso
data.event_idIdempotência. Não processe duas vezes o mesmo valor.
data.event_nameSlug do evento (pix-received, pix-sent, etc.).

Headers: Authorization quando autenticação foi configurada no cadastro. Responda HTTP 2xx rapidamente.

Responsabilidade do integrador: idempotência por data.event_id e validação de status (movement.status, newStatus/oldStatus, event_name) antes de operacionalizar na aplicação.

Schema OpenAPI: #/components/schemas/BaasAccountWebhookNotificacao. Exemplos no callback Entrega na url cadastrada do POST e em post-api-v2-baas-webhooks-examples.

Eventos e payloads completos: Webhooks da conta.

Notas

curl --request POST \
  --url 'https://api-h.nuvende.com.br/api/v2/baas/webhooks' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{access_token}}' \
  --header 'X-Timestamp: {{timestamp}}' \
  --header 'X-Nonce: {{nonce}}' \
  --header 'X-Signature: {{signature}}' \
  --data '{"url":"https://integrador.exemplo.com.br/webhooks/conta/pix","events":["pix-received","pix-sent","return-received"],"method":"POST","status":"ACTIVE"}'

const axios = require("axios");

const data = {
  "url": "https://integrador.exemplo.com.br/webhooks/conta/pix",
  "events": [
    "pix-received",
    "pix-sent",
    "return-received"
  ],
  "method": "POST",
  "status": "ACTIVE"
};

axios({
  method: "post",
  url: "https://api-h.nuvende.com.br/api/v2/baas/webhooks",
  headers: {
    "Content-Type": "application/json",
    Accept: "application/json",
    Authorization: "Bearer {{access_token}}",
    "X-Timestamp": "{{timestamp}}",
    "X-Nonce": "{{nonce}}",
    "X-Signature": "{{signature}}",
  },
  data,
})
  .then((response) => console.log(JSON.stringify(response.data)))
  .catch((error) => console.log(error.response?.data || error.message));

import json
import requests

url = "https://api-h.nuvende.com.br/api/v2/baas/webhooks"
payload = {
        "url": "https://integrador.exemplo.com.br/webhooks/conta/pix",
        "events": [
            "pix-received",
            "pix-sent",
            "return-received"
        ],
        "method": "POST",
        "status": "ACTIVE"
    }
headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "X-Timestamp": "{{timestamp}}",
    "X-Nonce": "{{nonce}}",
    "X-Signature": "{{signature}}",
}
response = requests.post(url, headers=headers, data=json.dumps(payload))
print(response.text)

<?php
$curl = curl_init();
$opts = [
  CURLOPT_URL => 'https://api-h.nuvende.com.br/api/v2/baas/webhooks',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => '{"url":"https://integrador.exemplo.com.br/webhooks/conta/pix","events":["pix-received","pix-sent","return-received"],"method":"POST","status":"ACTIVE"}',
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'Accept: application/json',
    'Authorization: Bearer {{access_token}}',
    'X-Timestamp: {{timestamp}}',
    'X-Nonce: {{nonce}}',
    'X-Signature: {{signature}}',
  ],
];
curl_setopt_array($curl, $opts);
$response = curl_exec($curl);
curl_close($curl);
echo $response;

{
  "id": 1,
  "url": "https://integrador.exemplo.com.br/webhooks/conta/pix",
  "status": "ACTIVE",
  "events": [
    "pix-received",
    "pix-sent"
  ],
  "method": "POST",
  "created_at": "2025-01-10T08:00:00Z"
}

{
  "data": {
    "event_id": 1001,
    "event_name": "pix-received",
    "customer": {
      "id": 500,
      "out_user_id": "user-abc-123",
      "name": "Maria Pagadora Exemplo",
      "document": "11144477735",
      "phone": "11999999999",
      "email": "[email protected]",
      "status": 1,
      "uuid": "550e8400-e29b-41d4-a716-446655440000"
    },
    "account": {
      "id": 800,
      "uuid": "acc-uuid-receiver",
      "name": "Maria Pagadora Exemplo",
      "document": "11144477735",
      "bank_id": 1,
      "agency": "0001",
      "account": "123456",
      "account_digit": "7",
      "primary": true
    },
    "movement": {
      "id": 9001,
      "uuid": "mov-uuid-001",
      "value": 150.5,
      "status": 1,
      "type": 0,
      "transaction_type": 0,
      "created_at": "2026-05-26T14:30:00+00:00"
    }
  }
}

{
  "data": {
    "event_id": 1002,
    "event_name": "pix-sent",
    "customer": {
      "id": 500,
      "out_user_id": "user-abc-123",
      "name": "Maria Pagadora Exemplo",
      "document": "11144477735",
      "phone": "11999999999",
      "email": "[email protected]",
      "status": 1,
      "uuid": "550e8400-e29b-41d4-a716-446655440000"
    },
    "account": {
      "id": 800,
      "uuid": "acc-uuid-payer",
      "name": "Maria Pagadora Exemplo",
      "document": "11144477735",
      "bank_id": 1,
      "agency": "0001",
      "account": "123456",
      "account_digit": "7",
      "primary": true
    },
    "movement": {
      "id": 9002,
      "uuid": "mov-uuid-002",
      "value": 75,
      "status": 1,
      "type": 1,
      "transaction_type": 0,
      "created_at": "2026-05-26T15:00:00+00:00"
    }
  }
}

{
  "data": {
    "event_id": 1004,
    "event_name": "person-status-updated",
    "customer": {
      "id": 500,
      "out_user_id": "user-abc-123",
      "name": "Maria Pagadora Exemplo",
      "document": "11144477735",
      "phone": "11999999999",
      "email": "[email protected]",
      "status": 2,
      "uuid": "550e8400-e29b-41d4-a716-446655440000"
    },
    "newStatus": 2,
    "oldStatus": 1
  }
}