POST/api/v2/baas/seller-webhooks
Criar
Produto BaaS (parceiro). Requer Bearer JWT do parceiro. Não exige assinatura HMAC neste recurso (alinhado ao SDK SellerWebhookResource). Scope: baas.seller-webhooks.write. Guia: documentação técnica.
Parâmetros
AcceptObrigatório
headerTipo:
stringAutenticação e headers
Requer Bearer token do parceiro (OAuth parceiro). Sem assinatura HMAC neste recurso.
Scope: baas.seller-webhooks.write.
| Header | Obrigatório | Descrição |
|---|---|---|
Authorization | Sim | Bearer {{access_token}} |
Accept | Sim | application/json |
Corpo
| Campo | Obrigatório | Descrição |
|---|---|---|
url | Sim | URL HTTPS de callback |
authentication_token | Sim | Segredo validado no receptor do callback (somente no corpo do POST/PATCH; não retornado nas respostas) |
entity | Sim | AccountCredentials ou AccountContract |
event_type | Sim | created, updated ou deleted (AccountCredentials: só created e updated) |
422 se campo obrigatório ausente.
Códigos
| Código | Descrição |
|---|---|
| 200 | OK |
| 201 | Recurso criado |
| 400 | Parâmetros inválidos |
| 401 | Token inválido |
| 403 | Scope ausente |
| 404 | Não encontrado |
| 422 | Validação ou regra de negócio |
| 500 | Erro interno |
Payload enviado ao parceiro (POST na url)
Quando entity + event_type disparam, a Nuvende faz POST na url cadastrada. Valide o authentication_token (header Authorization: Bearer …) antes de ler o corpo.
| Campo | Uso |
|---|---|
event | Espelha event_type. |
model | Espelha entity (AccountCredentials ou AccountContract). |
seller_id | Parceiro na raiz; repetido em data.seller_id. |
timestamp | Só em AccountContract. Ausente em AccountCredentials. |
data | Corpo serializado. Segredos (client_secret, hmac_secret, seller.hmac_secret) só aqui. |
AccountCredentials: sem deleted; added_scopes só em updated; client_secret omitido se vazio; client_id sempre presente (pode ser null).
AccountContract: contrato + relações (account, user, company, price_table, seller, etc.). FKs account_id, user_id, company_id, admin_id, business_unit_id, price_table_id não vêm no JSON.
Responda HTTP 2xx ou 202 rapidamente. Idempotência: account_uuid ou data.id + model + event.
Responsabilidade do integrador: garantir idempotência do processamento e validar event, model e status em data antes de operacionalizar (credenciais, contrato, onboarding).
Schema OpenAPI: #/components/schemas/BaasSellerWebhookNotificacao. Exemplos no callback Entrega na url cadastrada do POST e em post-api-v2-baas-seller-webhooks-examples.
Guias: Webhooks da plataforma.
Notas
- Técnica: Webhooks da plataforma.
- Visão geral BaaS: Sobre o BaaS.
curl --request POST \
--url 'https://api-h.nuvende.com.br/api/v2/baas/seller-webhooks' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data '{"url":"https://integrador.exemplo.com.br/webhooks/credenciais","authentication_token":"{{webhook_auth_token}}","entity":"AccountCredentials","event_type":"created"}'
const axios = require("axios");
const data = {
"url": "https://integrador.exemplo.com.br/webhooks/credenciais",
"authentication_token": "{{webhook_auth_token}}",
"entity": "AccountCredentials",
"event_type": "created"
};
axios({
method: "post",
url: "https://api-h.nuvende.com.br/api/v2/baas/seller-webhooks",
headers: {
"Content-Type": "application/json",
Accept: "application/json",
Authorization: "Bearer {{access_token}}",
},
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/seller-webhooks"
payload = {
"url": "https://integrador.exemplo.com.br/webhooks/credenciais",
"authentication_token": "{{webhook_auth_token}}",
"entity": "AccountCredentials",
"event_type": "created"
}
headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {{access_token}}",
}
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/seller-webhooks',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => '{"url":"https://integrador.exemplo.com.br/webhooks/credenciais","authentication_token":"{{webhook_auth_token}}","entity":"AccountCredentials","event_type":"created"}',
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'Accept: application/json',
'Authorization: Bearer {{access_token}}',
],
];
curl_setopt_array($curl, $opts);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
{
"id": 2,
"url": "https://integrador.exemplo.com.br/webhooks/credenciais",
"entity": "AccountCredentials",
"event_type": "created",
"status": "active",
"seller_id": 1001,
"created_at": "2025-01-10T08:00:00Z",
"updated_at": "2025-01-10T08:00:00Z"
}
{
"url": ["The url field is required."],
"authentication_token": ["The authentication token field is required."]
}
{
"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
}
}
{
"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
}
}
{
"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
}
}