Webhooks da plataforma

Direção do tráfego

Nuvende → servidor do parceiro na plataforma BaaS. Quando a plataforma gera ou altera artefatos como credenciais OAuth da conta ou contrato, a Nuvende POSTa na URL registrada em /api/v2/baas/seller-webhooks.

Não é o webhook da conta BaaS (/api/v2/baas/webhooks), que notifica Pix e eventos da conta titular (filtro opcional por domínio: pix-payments, onboardings, etc.). Ver Webhooks da conta.

Entidades (entity)

Somente estes valores no cadastro de seller webhook:

Regras de cadastro

• Um POST por event_type na criação: selecionar created + updated = dois registros com mesma URL base.
• authentication_token: segredo definido no cadastro; a Nuvende reenvia esse valor ao chamar sua URL, valide com hash_equals antes de processar o corpo. Não é retornado nas respostas de listagem, consulta, criação ou atualização.
• PATCH só altera url e opcionalmente authentication_token, reenviar entity/event_type causa 422.
• URL deve ser HTTPS pública e estável.

Como o callback chega na sua URL

Quando o evento cadastrado ocorre na Nuvende, ela faz um POST na url informada no registro (POST /baas/seller-webhooks). Não é um pedido assinado com HMAC de API Baas, a autenticação do callback é o authentication_token que você definiu no cadastro.

Pedido HTTP (exemplo)

POST /webhooks/nuvende HTTP/1.1
Host: seu-dominio.com.br
Content-Type: application/json
Authorization: Bearer {{webhook_auth_token}}

O token no header costuma ser o mesmo valor enviado em authentication_token ao criar o webhook. Em homologação, confirme se o gateway usa Authorization: Bearer … ou outro header; rejeite o pedido se o segredo não coincidir.

Corpo JSON: convenções

Não registre o corpo completo em logs. Campos nunca enviados: user.password, user.remember_token, user.register_token, admin.password, admin.remember_token, admin.google2fa_secret, charge_link_adiq_client_secret.

AccountCredentials

Disparado quando credenciais OAuth da conta ficam disponíveis ou mudam. Use para persistir client_id, client_secret, scopes, hmac_secret e habilitar Autenticação da conta BaaS.

created

{
  "event": "created",
  "model": "AccountCredentials",
  "seller_id": 12,
  "data": {
    "account_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "client_id": "a4bb5b06-4e72-4194-b4d7-770d6dbfda93",
    "name": "Aplicacao Integrador Exemplo",
    "partner_id": "00000000-0000-0000-0000-000000000099",
    "scopes": [
      "baas.balances.read",
      "baas.webhooks.write"
    ],
    "client_secret": "{{client_secret}}",
    "hmac_secret": "{{hmac_secret}}",
    "seller_id": 12
  }
}

updated

{
  "event": "updated",
  "model": "AccountCredentials",
  "seller_id": 12,
  "data": {
    "account_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "client_id": "a4bb5b06-4e72-4194-b4d7-770d6dbfda93",
    "name": "Aplicacao Integrador Exemplo",
    "partner_id": "00000000-0000-0000-0000-000000000099",
    "scopes": [
      "baas.balances.read",
      "baas.webhooks.write"
    ],
    "added_scopes": [
      "baas.webhooks.write"
    ],
    "client_secret": "{{client_secret}}",
    "hmac_secret": "{{hmac_secret}}",
    "seller_id": 12
  }
}

Correlacione pelo account_uuid em data.

AccountContract

Disparado quando um contrato de conta é criado, alterado ou removido. O data traz o contrato e relações aninhadas (price_table, account, user, company, admin, business_unit, seller).

Exemplo created (corpo completo serializado, dados fictícios):

{
  "event": "created",
  "seller_id": 12,
  "model": "AccountContract",
  "timestamp": "2026-07-17T17:30:00-03:00",
  "data": {
    "id": 501,
    "company_branch_id": null,
    "name": "Contrato principal",
    "type": "monthly",
    "status": "approved",
    "capture_block": false,
    "payment_schedule_block": false,
    "deregistration_reason": "not_informed",
    "allows_schedule_transfer": false,
    "pos_rent_charge": true,
    "allows_receivables_anticipation": true,
    "enables_transaction_cancellation": false,
    "enables_tap_on_phone": false,
    "enable_pix_accreditation": true,
    "block_receipt_via_pix": false,
    "allows_cash_out": true,
    "start_date": "2026-07-01T00:00:00.000000Z",
    "end_date": "2027-07-01T00:00:00.000000Z",
    "segment": "varejo",
    "charge_link_type": "pagseguro",
    "charge_link_adiq_client_id": null,
    "has_split": false,
    "advance_cushion": 0,
    "signed_at": "2026-07-01T00:00:00.000000Z",
    "created_at": "2026-07-01T00:00:00.000000Z",
    "updated_at": "2026-07-17T17:30:00.000000Z",
    "deleted_at": null,
    "first_open_hour": "07:00:00",
    "first_close_hour": "12:00:00",
    "second_open_hour": "13:00:00",
    "second_close_hour": "19:00:00",
    "risk_classification": "not_defined",
    "risk_region": false,
    "price_table": {
      "id": 22,
      "seller_id": 12,
      "name": "Tabela padrao",
      "status": "active",
      "global": false,
      "use_as_default": true,
      "show_in_app": true,
      "reference_value": null,
      "start_date": "2026-01-01T00:00:00.000000Z",
      "end_date": "2027-01-01T00:00:00.000000Z",
      "created_at": "2026-01-01T00:00:00.000000Z",
      "updated_at": "2026-01-01T00:00:00.000000Z",
      "deleted_at": null
    },
    "account": {
      "id": 100,
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "old_balance": 0,
      "balance": 0,
      "name": "Conta principal",
      "user_id": 98765,
      "company_id": null,
      "bank_id": 260,
      "agency": "0001",
      "agency_vd": null,
      "account": "1234567",
      "account_vd": "8",
      "type": "checking",
      "last_update_balance_at": null,
      "last_access_at": null,
      "tags": null,
      "natural_daytime_limit": null,
      "natural_nighttime_limit": null,
      "legal_daytime_limit": null,
      "legal_nighttime_limit": null,
      "blocked_balance": 0,
      "reserved_balance": 0,
      "pix_limit_pf_diurno": 0,
      "pix_limit_pf_noturno": 0,
      "pix_limit_pj_daily": 0,
      "pix_limit_agendado": 0,
      "pix_limit_automatico": 0,
      "transaction_limit": 0,
      "created_at": "2026-07-01T00:00:00.000000Z",
      "updated_at": "2026-07-17T17:30:00.000000Z",
      "deleted_at": null
    },
    "user": {
      "id": 98765,
      "uuid": null,
      "name": "Maria Pagadora Exemplo",
      "email": "[email protected]",
      "auth_code": null,
      "telephone": null,
      "cellphone": "11999999999",
      "document": "11144477735",
      "document_type": "cpf",
      "document_number": null,
      "document_issue_date": null,
      "document_issuing_agency_id": null,
      "document_issuer_state_id": null,
      "document_image": null,
      "birth_date": "1990-01-01T00:00:00.000000Z",
      "country_of_birth_id": 1,
      "marital_status": "single",
      "gender": "female",
      "mother_name": null,
      "mother_name_unknown": false,
      "father_name": null,
      "father_name_unknown": false,
      "address_zip_code": "01001000",
      "address_state_id": 25,
      "address_city_id": 1,
      "address_neighborhood_id": 1,
      "address_street": "Rua Exemplo",
      "address_number": "100",
      "address_complement": null,
      "address_image": null,
      "monthly_income": 0,
      "profession": null,
      "vehicles_qty": 0,
      "vehicles_value": 0,
      "commercial_property_qty": 0,
      "commercial_property_value": 0,
      "residential_property_qty": 0,
      "residential_property_value": 0,
      "university_student": false,
      "politically_exposed": false,
      "foreign_activities": false,
      "classification": "string",
      "seller_id": 12,
      "seller": false,
      "technician": false,
      "status": "active",
      "documents_status": "approved",
      "avatar": null,
      "restricted_lists_search": null,
      "background_check_days": 0,
      "document_file_path": null,
      "back_document_file_path": null,
      "address_file_path": null,
      "created_at": "2026-07-01T00:00:00.000000Z",
      "updated_at": "2026-07-17T17:30:00.000000Z",
      "deleted_at": null
    },
    "company": {
      "id": 54321,
      "state_id": 25,
      "city_id": 1,
      "neighborhood_id": 1,
      "legal_representative_user_id": 98765,
      "seller_id": 12,
      "classification": "string",
      "status": "active",
      "documents_status": "approved",
      "document": "43587980000107",
      "document_file": null,
      "legal_nature": null,
      "name": "Loja Exemplo LTDA",
      "corporate_name": "Loja Exemplo LTDA",
      "business_name": "Loja Exemplo",
      "nation_classification_economic_activities": null,
      "merchant_category_classification": null,
      "municipal_registration": null,
      "municipal_registration_file": null,
      "state_registration": null,
      "state_registration_exempt": false,
      "state_registration_file": null,
      "telephone": null,
      "cellphone": "11999999999",
      "email": "[email protected]",
      "zip_code": "01001000",
      "full_address": null,
      "address_number": "100",
      "address_complement": null,
      "address_file": null,
      "address_zip_code": "01001000",
      "address_state_id": 25,
      "address_city_id": 1,
      "address_neighborhood_id": 1,
      "address_street": "Rua Exemplo",
      "address_image": null,
      "restricted_lists_to_check": null,
      "background_check_days": 0,
      "last_background_check": null,
      "monthly_billing": 0,
      "asset_value": 0,
      "advance_cushion": 0,
      "risk_classification": null,
      "commercial_classification": null,
      "rentability_classification": null,
      "founded_at": null,
      "representative_name": null,
      "representative_cpf": null,
      "representative_birthdate": null,
      "representative_nationality": null,
      "representative_politically_exposed": false,
      "representative_occupation": null,
      "document_image": null,
      "monthly_income": 0,
      "vehicles_qty": 0,
      "vehicles_value": 0,
      "commercial_property_qty": 0,
      "commercial_property_value": 0,
      "residential_property_qty": 0,
      "residential_property_value": 0,
      "avatar": null,
      "restricted_lists_search": null,
      "document_file_path": null,
      "back_document_file_path": null,
      "address_file_path": null,
      "created_at": "2026-07-01T00:00:00.000000Z",
      "updated_at": "2026-07-17T17:30:00.000000Z",
      "deleted_at": null
    },
    "admin": {
      "id": 1,
      "seller_id": 12,
      "name": "Administrador Exemplo",
      "email": "[email protected]",
      "phone": null,
      "document": null,
      "birth_date": null,
      "seller": false,
      "status": "active",
      "created_at": "2026-01-01T00:00:00.000000Z",
      "updated_at": "2026-01-01T00:00:00.000000Z",
      "deleted_at": null
    },
    "business_unit": {
      "id": 1,
      "name": "Unidade principal",
      "code": "MAIN",
      "created_at": "2026-01-01T00:00:00.000000Z",
      "updated_at": "2026-01-01T00:00:00.000000Z",
      "deleted_at": null
    },
    "seller": {
      "id": 12,
      "sub_acquirer_id": 1,
      "company_id": 54321,
      "status": "active",
      "name": "Parceiro Exemplo",
      "is_default": false,
      "is_baas": true,
      "support_phone": null,
      "website": null,
      "activation_date": null,
      "deactivation_date": null,
      "contact_name": null,
      "contact_email": null,
      "contact_phone": null,
      "hmac_secret": "{{hmac_secret}}",
      "created_at": "2026-01-01T00:00:00.000000Z",
      "updated_at": "2026-01-01T00:00:00.000000Z",
      "deleted_at": null
    },
    "seller_id": 12
  }
}

Em updated e deleted, a mesma estrutura base se repete com estado atualizado; trate idempotência no seu lado.

Resposta esperada do seu servidor

Responda rápido (idealmente 202 ou 200) com JSON curto, por exemplo:

{ "id": 12345 }

Processe o payload de forma assíncrona se a lógica for pesada. Repetir o mesmo evento não deve duplicar credenciais ou contratos, use account_uuid + model + event como chave de idempotência.

Entrega e retentativas

Responsabilidade do integrador

É responsabilidade do integrador garantir a idempotência do processamento (mesmo account_uuid + model + event não deve duplicar credenciais ou contratos) e validar event e status em data (ex.: data.status do contrato, documents_status do titular) antes de operacionalizar na aplicação. Confirme que event e model batem com o registro cadastrado antes de persistir segredos ou alterar fluxos de onboarding.

Erros comuns no ingress

• 401, token ausente ou diferente do authentication_token cadastrado.
• Timeout na Nuvende, endpoint lento ou indisponível; use fila interna.
• Credenciais gravadas do evento errado, vários owners: identifique o tenant por account_uuid / client_id no data, não só pelo evento mais recente.

Uso operacional

Após onboarding aprovado, espere AccountCredentials created para habilitar Autenticação da conta BaaS com credenciais recebidas no data do callback (não expor em logs).

Endpoints

Criar

Pedido

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

Observações

Um POST por event_type.

Regras de negócio

• Um registro por combinação URL + entity + event_type.
• authentication_token será reenviado pela Nuvende no callback (Authorization: Bearer … na prática), guarde com segurança e valide antes de ler o JSON.
• Evento AccountCredentials created é o gatilho típico para armazenar credenciais OAuth do titular.

Exemplo cURL

curl --request POST \
  --url "https://api.nuvende.com.br/api/v2/baas/seller-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",
  "authentication_token": "{{webhook_auth_token}}",
  "entity": "AccountContract",
  "event_type": "created"
}'

Corpo de exemplo

{
  "url": "https://integrador.exemplo.com.br/webhooks/edd2f8a2-3cb4-4d32-877a-3b589047bf7c",
  "authentication_token": "{{webhook_auth_token}}",
  "entity": "AccountContract",
  "event_type": "created"
}

Resposta 201: Created

{
  "id": 8,
  "seller_id": 45,
  "url": "https://integrador.exemplo.com.br/webhooks/edd2f8a2-3cb4-4d32-877a-3b589047bf7c",
  "entity": "AccountCredentials",
  "event_type": "created",
  "status": "active",
  "created_at": "2026-05-08T10:26:48-03:00",
  "updated_at": "2026-05-08T10:26:48-03:00"
}

Resposta 201: Created

{
  "id": 9,
  "seller_id": 45,
  "url": "https://integrador.exemplo.com.br/webhooks/edd2f8a2-3cb4-4d32-877a-3b589047bf7c",
  "entity": "AccountCredentials",
  "event_type": "updated",
  "status": "active",
  "created_at": "2026-05-08T10:27:22-03:00",
  "updated_at": "2026-05-08T10:27:22-03:00"
}

Resposta 201: Created

{
  "id": 10,
  "seller_id": 45,
  "url": "https://integrador.exemplo.com.br/webhooks/edd2f8a2-3cb4-4d32-877a-3b589047bf7c",
  "entity": "AccountContract",
  "event_type": "updated",
  "status": "active",
  "created_at": "2026-05-08T11:26:28-03:00",
  "updated_at": "2026-05-08T11:26:28-03:00"
}

Resposta 201: Created

{
  "id": 11,
  "seller_id": 45,
  "url": "https://integrador.exemplo.com.br/webhooks/edd2f8a2-3cb4-4d32-877a-3b589047bf7c",
  "entity": "AccountContract",
  "event_type": "created",
  "status": "active",
  "created_at": "2026-05-08T11:27:15-03:00",
  "updated_at": "2026-05-08T11:27:15-03:00"
}

Atualizar

Pedido

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

Apenas url e opcionalmente authentication_token. Não envie entity / event_type.

Regras de negócio

• Só mudança de URL de destino ou token.
• Entity/event imutáveis, criar novo registro se precisar outro evento.

Exemplo cURL

curl --request PATCH \
  --url "https://api.nuvende.com.br/api/v2/baas/seller-webhooks/11" \
  --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",
  "authentication_token": "{{webhook_auth_token}}"
}'

Corpo de exemplo

{
  "url": "https://integrador.exemplo.com.br/webhooks/edd2f8a2-3cb4-4d32-877a-3b589047bf7c",
  "authentication_token": "{{webhook_auth_token}}"
}

Excluir

Pedido

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

• Para de receber callbacks daquele webhookId.
• Não apaga eventos já enfileirados.

Exemplo cURL

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

Listar

Pedido

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 []

Função

Lista seller webhooks cadastrados.

Regras de negócio

• Lista subscriptions seller do parceiro.
• Cada registro = um entity + event_type + URL.

Exemplo cURL

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

Consultar

Pedido

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 []

Função

Detalhe de um seller webhook.

Regras de negócio

• Detalhe inclui URL e entity fixos; útil para auditoria de cadastro.

Exemplo cURL

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