Webhooks da conta

Configure webhooks de notificações para a conta BaaS (titular).

Direção

Nuvende → URL HTTPS cadastrada em POST /api/v2/baas/webhooks. Notifica eventos desta conta (Pix, devolução, status cadastral, conta criada no onboarding).

Distinto dos Webhooks da plataforma (/api/v2/baas/seller-webhooks), usados somente para AccountCredentials e AccountContract.

Credencial: token da Autenticação da conta BaaS.

Eventos cadastráveis

Somente estes valores podem constar em events[] no cadastro do webhook:

Evento
`pix-received`
`pix-sent`
`return-received`
`person-status-updated`
`onboarding-proposal-natural-account-created`
`onboarding-proposal-legal-account-created`

Eventos como boleto-paid, transfer-in, pix-refund ou outros slugs não fazem parte deste cadastro BaaS de conta.

Filtro opcional (`entity`)

Restringe entregas a um domínio da conta. Valores permitidos no cadastro:

`entity`	Domínio
`contracts`	Contratos da conta
`onboardings`	Onboarding
`pix-payments`	Pix (cash-in e cash-out)
`accounts`	Conta titular
`key-managements`	Chaves Pix
`bankslip-payments`	Pagamentos de boleto

Omita entity para receber todos os eventos de events[] sem filtro de domínio.

Formato da notificação (callback)

Nuvende envia POST para a URL cadastrada. Não é endpoint que o integrador chama na API pública: é o payload inbound que seu servidor deve receber e validar.

Todas as notificações chegam por POST com corpo JSON:

{
  "data": {
    "event_id": 12345,
    "event_name": "nome-do-evento",
    "...": "campos específicos do evento"
  }
}

Campo	Uso
`event_id`	Identificador único da notificação, use para idempotência (mesmo `event_id` não deve processar duas vezes).
`event_name`	Um dos eventos da tabela acima.

Se autenticação foi configurada no cadastro, o header Authorization segue o tipo e o segredo informados (ex.: Bearer seu-token).

Responda 2xx rapidamente; processe o payload de forma assíncrona se necessário. Falha (timeout ou resposta não 2xx) exige reenvio manual com POST /api/v2/baas/webhooks/resend e o mesmo event_id.

Entrega e retentativas

Aspecto	Regra
Método	POST na `url` cadastrada (ou `method` configurado: `PUT` / `PATCH`)
Autenticação inbound	Header `Authorization` conforme segredo do cadastro, se configurado
Sucesso	HTTP 2xx confirma recebimento
Tempo de resposta	Responda antes de lógica pesada; use fila interna
Idempotência	Mesmo `data.event_id` não deve gerar efeito duplicado no integrador
Falha na entrega	`POST /api/v2/baas/webhooks/resend` com `event_id` ou intervalo `start_date` + `end_date` (processamento assíncrono, retorna 202)

Diferente dos webhooks de cobrança Pix (Mundo Digital), este fluxo não documenta retentativas automáticas a cada 300 s. O reenvio é solicitado pelo titular via API.

Responsabilidade do integrador

É responsabilidade do integrador garantir a idempotência do processamento do webhook (mesmo data.event_id ou reentrega via /resend não pode duplicar efeitos na aplicação) e validar os campos de status do payload antes de operacionalizar.

Contexto	Validar antes de agir
Pix (`pix-received`, `pix-sent`, `return-received`)	`movement.status` (`1` = concluída; `0` pendente; `2` falhou)
Cadastro (`person-status-updated`)	`newStatus` / `oldStatus` e coerência com `customer.status`
Onboarding (conta criada)	`event_name` esperado e dados mínimos em `account` / `company`
Qualquer evento	`data.event_name` corresponde ao slug inscrito; ignore estados que sua regra não trata

Não assuma que todo POST inbound exige ação imediata: confira status e idempotência, depois creditar, debitar ou atualizar cadastro na sua aplicação.

`pix-received`

Disparado quando um Pix é creditado na conta do titular.

{
  "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.50,
      "status": 1,
      "type": 0,
      "transaction_type": 0,
      "created_at": "2026-05-26T14:30:00+00:00"
    }
  }
}

movement.status: 0 pendente · 1 concluída · 2 falhou

movement.type: 0 entrada · 1 saída · 2 transferência · 3 estorno

`pix-sent`

Disparado quando um Pix é enviado pela conta do titular e concluído.

{
  "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.00,
      "status": 1,
      "type": 1,
      "transaction_type": 0,
      "created_at": "2026-05-26T15:00:00+00:00"
    }
  }
}

account é sempre a conta pagadora (quem enviou o Pix).

`return-received`

Disparado quando uma devolução de Pix é creditada na conta do titular.

{
  "data": {
    "event_id": 1003,
    "event_name": "return-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": 9003,
      "uuid": "mov-uuid-003",
      "value": 50.00,
      "status": 1,
      "type": 1,
      "transaction_type": 0,
      "created_at": "2026-05-26T16:00:00+00:00"
    }
  }
}

`person-status-updated`

Disparado quando o status cadastral do titular (pessoa física) é alterado.

{
  "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
  }
}

`onboarding-proposal-natural-account-created`

Disparado quando uma conta de pessoa física é criada no onboarding.

{
  "data": {
    "event_id": 1005,
    "event_name": "onboarding-proposal-natural-account-created",
    "customer": {
      "id": 500,
      "out_user_id": "user-abc-123",
      "name": "Maria Pagadora Exemplo",
      "document": "11144477735",
      "phone": "11999999999",
      "email": "[email protected]",
      "uuid": "550e8400-e29b-41d4-a716-446655440000"
    },
    "account": {
      "id": 801,
      "uuid": "nova-conta-uuid",
      "name": "Maria Pagadora Exemplo",
      "document": "11144477735",
      "bank_id": 1,
      "agency": "0001",
      "account": "654321",
      "account_digit": "0",
      "primary": true
    }
  }
}

`onboarding-proposal-legal-account-created`

Disparado quando uma conta de pessoa jurídica é criada no onboarding.

{
  "data": {
    "event_id": 1006,
    "event_name": "onboarding-proposal-legal-account-created",
    "company": {
      "id": 300,
      "out_company_id": "company-ext-456",
      "name": "Loja Exemplo LTDA",
      "document": "43587980000107",
      "phone": "1133334444",
      "email": "[email protected]",
      "uuid": "660e8400-e29b-41d4-a716-446655440001"
    },
    "account": {
      "id": 802,
      "uuid": "conta-pj-uuid",
      "name": "Loja Exemplo LTDA",
      "document": "43587980000107",
      "bank_id": 1,
      "agency": "0001",
      "account": "111222",
      "account_digit": "3",
      "primary": true
    }
  }
}

Cadastro na API (`events[]`)

Exemplo de corpo ao Criar webhook (ver operação Criar):

{
  "url": "https://seu-dominio.com/webhooks/conta",
  "events": [
    "pix-received",
    "pix-sent",
    "return-received",
    "person-status-updated",
    "onboarding-proposal-natural-account-created",
    "onboarding-proposal-legal-account-created"
  ],
  "method": "POST",
  "status": "ACTIVE"
}

Campos opcionais no cadastro: method (POST, PUT, PATCH), status (ACTIVE, INACTIVE, PENDING), entity (filtro por domínio; ver tabela acima).


Método	`GET`
Path	`/api/v2/baas/webhooks`
URL	`{{base_url}}/api/v2/baas/webhooks`

Autenticação

Authorization: Bearer {{access_token}}
X-Timestamp → {{timestamp}}
X-Nonce → {{nonce}}
X-Signature → {{signature}} (HMAC-SHA256; segredo em {{hmac_secret}})
Mensagem: METHOD\nPATH\nQUERY\nBODY\nTIMESTAMP\nNONCE, PATH inclui /api/v2/...
Em vários GET assinados o BODY na assinatura é o literal []

Scope OAuth

baas.webhooks.read

Regras de negócio

Lista inscrições do titular (url, events, status, etc.).
Eventos cadastráveis e payloads de callback: README desta pasta.

Exemplo cURL

curl --request GET \
  --url "https://api.nuvende.com.br/api/v2/baas/webhooks" \
  --header "Authorization: Bearer {{access_token}}" \
  --header "X-Timestamp: {{timestamp}}" \
  --header "X-Nonce: {{nonce}}" \
  --header "X-Signature: {{signature}}" \
  --header "Content-Type: application/json"

Criar

Pedido


Método	`POST`
Path	`/api/v2/baas/webhooks`
URL	`{{base_url}}/api/v2/baas/webhooks`

Scope OAuth

baas.webhooks.write (token de conta). Inclua também baas.webhooks.read se for listar depois.

Headers

Authorization: Bearer {{access_token}}
Content-Type: application/json
X-Timestamp → {{timestamp}}
X-Nonce → {{nonce}}
X-Signature → {{signature}} (HMAC-SHA256; segredo em {{hmac_secret}})
Mensagem HMAC: METHOD\nPATH\nQUERY\nBODY\nTIMESTAMP\nNONCE, BODY = JSON exato enviado.

Corpo (`application/json`)

Campo	Regra
`url`	Obrigatório. HTTPS público que receberá os callbacks.
`events`	Obrigatório. Array com pelo menos um evento, apenas os seis slugs documentados no README desta pasta.
`method`	Opcional. Como a Nuvende chama sua URL: `POST` (recomendado), `PUT` ou `PATCH`.
`status`	Opcional. `ACTIVE`, `INACTIVE`, `PENDING`, só `ACTIVE` entrega notificações.
`entity`	Opcional. Filtro por domínio: `contracts`, `onboardings`, `pix-payments`, `accounts`, `key-managements`, `bankslip-payments`.

`events[]`: valores permitidos

Evento
`pix-received`
`pix-sent`
`return-received`
`person-status-updated`
`onboarding-proposal-natural-account-created`
`onboarding-proposal-legal-account-created`

Exemplo

{
  "url": "https://seu-dominio.com/webhooks/conta",
  "events": [
    "pix-received",
    "pix-sent",
    "return-received"
  ],
  "method": "POST",
  "status": "ACTIVE"
}

Regras de negócio

Slugs fora da lista acima tendem a 422 no cadastro.
Formato do POST que a Nuvende enviará na url: ver README desta pasta (wrapper data, event_id, event_name).
Configure autenticação do callback no cadastro se o gateway exigir, a Nuvende reenvia no header Authorization conforme o segredo informado.

Exemplo cURL

curl --request POST \
  --url "https://api.nuvende.com.br/api/v2/baas/webhooks" \
  --header "Authorization: Bearer {{access_token}}" \
  --header "X-Timestamp: {{timestamp}}" \
  --header "X-Nonce: {{nonce}}" \
  --header "X-Signature: {{signature}}" \
  --header "Content-Type: application/json" \
  --data '{
  "url": "https://integrador.exemplo.com.br/webhooks/edd2f8a2-3cb4-4d32-877a-3b589047bf7c",
  "method": "POST",
  "status": "ACTIVE",
  "secret_type": "Bearer",
  "secret": "{{webhook_secret}}",
  "events": [
    "pix-sent",
    "person-status-updated",
    "onboarding-proposal-legal-account-created",
    "onboarding-proposal-natural-account-created",
    "pix-received",
    "pix-sent",
    "return-received"
  ],
  "entity": "pix-payments"
}'

Corpo de exemplo

{
  "url": "https://integrador.exemplo.com.br/webhooks/edd2f8a2-3cb4-4d32-877a-3b589047bf7c",
  "method": "POST",
  "status": "ACTIVE",
  "secret_type": "Bearer",
  "secret": "{{webhook_secret}}",
  "events": [
    "pix-sent",
    "person-status-updated",
    "onboarding-proposal-legal-account-created",
    "onboarding-proposal-natural-account-created",
    "pix-received",
    "pix-sent",
    "return-received"
  ],
  "entity": "pix-payments"
}

Resposta 200: OK

{
  "id": 4,
  "status": "ACTIVE",
  "url": "https://integrador.exemplo.com.br/webhooks/2b861b03-1596-4d10-a48e-a5cd4256b06f",
  "events": [
    "person-status-updated",
    "onboarding-proposal-legal-account-created",
    "onboarding-proposal-natural-account-created",
    "pix-received",
    "pix-sent",
    "return-received"
  ],
  "created_at": null,
  "updated_at": null,
  "secret_type": null,
  "secret": null
}

Resposta 200: OK

{
  "id": 7,
  "status": "ACTIVE",
  "url": "https://integrador.exemplo.com.br/webhooks/347b0767-e3fe-4e37-9f92-5ff0fc55510e",
  "events": [
    "pix-sent",
    "person-status-updated",
    "onboarding-proposal-legal-account-created",
    "onboarding-proposal-natural-account-created",
    "pix-received",
    "pix-sent",
    "return-received"
  ],
  "created_at": null,
  "updated_at": null,
  "secret_type": "Bearer",
  "secret": "{{webhook_secret}}"
}

Consultar

Pedido


Método	`GET`
Path	`/api/v2/baas/webhooks/{id}`
URL	`{{base_url}}/api/v2/baas/webhooks/{id}`

Autenticação

Authorization: Bearer {{access_token}}
X-Timestamp → {{timestamp}}
X-Nonce → {{nonce}}
X-Signature → {{signature}} (HMAC-SHA256; segredo em {{hmac_secret}})
Mensagem: METHOD\nPATH\nQUERY\nBODY\nTIMESTAMP\nNONCE, PATH inclui /api/v2/...
Em vários GET assinados o BODY na assinatura é o literal []

Regras de negócio

Detalhe de eventos inscritos e URL de um id específico.

Exemplo cURL

curl --request GET \
  --url "https://api.nuvende.com.br/api/v2/baas/webhooks/{id}" \
  --header "Authorization: Bearer {{access_token}}" \
  --header "X-Timestamp: {{timestamp}}" \
  --header "X-Nonce: {{nonce}}" \
  --header "X-Signature: {{signature}}" \
  --header "Content-Type: application/json" \
  --data '[]'

Corpo de exemplo

[]

Atualizar

Pedido


Método	`PATCH`
Path	`/api/v2/baas/webhooks/{id}`
URL	`{{base_url}}/api/v2/baas/webhooks/{id}`

Autenticação

Authorization: Bearer {{access_token}}
X-Timestamp → {{timestamp}}
X-Nonce → {{nonce}}
X-Signature → {{signature}} (HMAC-SHA256; segredo em {{hmac_secret}})
Mensagem: METHOD\nPATH\nQUERY\nBODY\nTIMESTAMP\nNONCE, PATH inclui /api/v2/...
Em vários GET assinados o BODY na assinatura é o literal []

Regras de negócio

Pode pausar entregas com status INACTIVE sem excluir registro.

Exemplo cURL

curl --request PATCH \
  --url "https://api.nuvende.com.br/api/v2/baas/webhooks/10" \
  --header "Authorization: Bearer {{access_token}}" \
  --header "X-Timestamp: {{timestamp}}" \
  --header "X-Nonce: {{nonce}}" \
  --header "X-Signature: {{signature}}" \
  --header "Content-Type: application/json" \
  --data '{
  "id": 10,
  "status": "ACTIVE",
  "url": "https://integrador.exemplo.com.br/webhooks/edd2f8a2-3cb4-4d32-877a-3b589047bf7c",
  "events": [
    "pix-sent",
    "person-status-updated",
    "onboarding-proposal-legal-account-created",
    "onboarding-proposal-natural-account-created",
    "pix-received",
    "pix-sent",
    "return-received"
  ],
  "secret_type": "Bearer",
  "secret": "********"
}'

Corpo de exemplo

{
  "id": 10,
  "status": "ACTIVE",
  "url": "https://integrador.exemplo.com.br/webhooks/edd2f8a2-3cb4-4d32-877a-3b589047bf7c",
  "events": [
    "pix-sent",
    "person-status-updated",
    "onboarding-proposal-legal-account-created",
    "onboarding-proposal-natural-account-created",
    "pix-received",
    "pix-sent",
    "return-received"
  ],
  "secret_type": "Bearer",
  "secret": "********"
}

Resposta 200: OK

{
  "id": 10,
  "status": "ACTIVE",
  "url": "https://integrador.exemplo.com.br/webhooks/edd2f8a2-3cb4-4d32-877a-3b589047bf7c",
  "events": [
    "pix-sent",
    "person-status-updated",
    "onboarding-proposal-legal-account-created",
    "onboarding-proposal-natural-account-created",
    "pix-received",
    "pix-sent",
    "return-received"
  ],
  "created_at": null,
  "updated_at": null,
  "secret_type": "Bearer",
  "secret": "********"
}

Excluir

Pedido


Método	`DELETE`
Path	`/api/v2/baas/webhooks/{id}`
URL	`{{base_url}}/api/v2/baas/webhooks/{id}`

Autenticação

Authorization: Bearer {{access_token}}
X-Timestamp → {{timestamp}}
X-Nonce → {{nonce}}
X-Signature → {{signature}} (HMAC-SHA256; segredo em {{hmac_secret}})
Mensagem: METHOD\nPATH\nQUERY\nBODY\nTIMESTAMP\nNONCE, PATH inclui /api/v2/...
Em vários GET assinados o BODY na assinatura é o literal []

Regras de negócio

Remove subscription; eventos em voo podem ainda ser entregues uma vez.

Exemplo cURL

curl --request DELETE \
  --url "https://api.nuvende.com.br/api/v2/baas/webhooks/{id}" \
  --header "Authorization: Bearer {{access_token}}" \
  --header "X-Timestamp: {{timestamp}}" \
  --header "X-Nonce: {{nonce}}" \
  --header "X-Signature: {{signature}}"

Reenviar

Pedido


Método	`POST`
Path	`/api/v2/baas/webhooks/resend`
URL	`{{base_url}}/api/v2/baas/webhooks/resend`

Autenticação

Authorization: Bearer {{access_token}}
X-Timestamp → {{timestamp}}
X-Nonce → {{nonce}}
X-Signature → {{signature}} (HMAC-SHA256; segredo em {{hmac_secret}})
Mensagem: METHOD\nPATH\nQUERY\nBODY\nTIMESTAMP\nNONCE, PATH inclui /api/v2/...
Em vários GET assinados o BODY na assinatura é o literal []

Corpo

event_id, reprocessa entrega do evento.

Regras de negócio

event_id é o mesmo recebido em data.event_id no callback (ver README desta pasta).
Identifica falha de entrega anterior (seu endpoint retornou erro ou timeout).
Não duplica lançamento financeiro, só reentrega HTTP; trate idempotência pelo event_id.

Exemplo cURL

curl --request POST \
  --url "https://api.nuvende.com.br/api/v2/baas/webhooks/resend" \
  --header "Authorization: Bearer {{access_token}}" \
  --header "X-Timestamp: {{timestamp}}" \
  --header "X-Nonce: {{nonce}}" \
  --header "X-Signature: {{signature}}" \
  --header "Content-Type: application/json" \
  --data '{
  "event_id": "1"
}'

Corpo de exemplo

{
  "event_id": "1"
}

Conta BaaS

Jornada do titular: saldo, Pix, boletos, limites e webhooks da conta.

Autenticação da plataforma BaaS

OAuth e assinatura HMAC para operações de plataforma BaaS (onboarding, seller webhooks, contratos).