Webhooks de saída: ProPartners → seu sistema

O ProPartners avisa o seu sistema quando algo acontece no programa de parceiros: um lead novo, um contrato fechado, uma comissão confirmada, um Pix pago. Você cadastra uma URL, escolhe os eventos e passa a receber um POST assinado a cada fato. Serve para os dois lados:

• Fornecedor (empresa que paga comissão por indicação): recebe os fatos do próprio programa, com os dados do cliente sem máscara (o cliente é seu). É assim que o seu CRM, ERP ou sistema de atendimento começa a prospecção no momento em que o lead chega, e é por aqui que ele entrega as mensagens aos seus parceiros e leads (evento notify.message).
• Parceiro (afiliado que indica clientes): recebe só os fatos das próprias indicações, por grupos (indicações, contratos, pagamentos). O nome do cliente vai mascarado (João •••), salvo se o fornecedor liberou o nome completo. E-mail, telefone e documento do cliente nunca vão ao parceiro.

Quer enviar dados ao ProPartners (contratos, faturas, pagamentos do seu ERP)? Veja os webhooks de entrada. A API REST completa está em dashboard.propartners.com.br/api/v1/docs.

1. Cadastro do endpoint

Pela tela (Minha Conta → Webhooks para o fornecedor; Meus dados → Webhooks para o parceiro) ou pela API. Tudo o que a tela faz existe na API.

POST /api/v1/webhooks/endpoints/
{"label": "Atendimento", "url": "https://sistema.fornecedor.com.br/propartners",
 "events": ["lead.created", "lead.consent", "notify.message"]}

POST /api/v1/me/affiliate/webhooks/
{"label": "Minha planilha", "url": "https://hooks.exemplo.com/abc", "groups": ["indicacoes", "pagamentos"]}

A resposta do cadastro (e da troca de segredo) traz o secret uma única vez. Guarde-o: ele não aparece em nenhuma listagem. Perdeu? Gere outro em rotate-secret (o anterior deixa de valer na hora).

Regras: - URL https, sem usuário/senha embutidos. - Endereços internos são recusados (localhost, IPs privados, *.local, *.internal e domínios que apontam para rede interna), no cadastro e antes de cada envio. - Até 10 endpoints por dono. Fornecedor: lista de eventos vazia = todos os eventos (inclusive os que forem criados no futuro). Parceiro: ao menos um grupo.

2. Formato do envio

POST na URL cadastrada, corpo JSON UTF-8 com chaves ordenadas, timeout de 10 segundos. Redirecionamentos não são seguidos.

Envelope de todo evento:

{
  "created_at": "2026-09-29T13:08:34.635395+00:00",
  "data": {"…": "conteúdo do evento"},
  "event": "lead.created",
  "event_id": "lead.created:bdc3b01f…"
}

event_id identifica o fato (o mesmo para todos os endpoints); X-ProPartners-Delivery identifica a entrega a um endpoint. O mesmo fato chega no máximo uma vez a cada endpoint.

Validando a assinatura

Assine e valide o corpo exatamente como recebido (não re-serialize o JSON).

import hashlib, hmac

def assinatura_valida(corpo_bruto: bytes, assinatura: str, segredo: str) -> bool:
    esperado = hmac.new(segredo.encode(), corpo_bruto, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperado, assinatura or "")

// Node.js (Express com express.raw({type: "application/json"}))
const crypto = require("crypto");
function assinaturaValida(corpoBruto, assinatura, segredo) {
  const esperado = crypto.createHmac("sha256", segredo).update(corpoBruto).digest("hex");
  return assinatura && crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(assinatura));
}

3. Respostas, retry e replay

• Qualquer 2xx = entregue.
• Falha de rede, timeout, 5xx, 408 ou 429: nova tentativa em cerca de 1 minuto e de 5 minutos (3 tentativas no total). Esgotou = falha.
• Outros 4xx e 3xx: falha na hora (o seu sistema recusou; repetir não muda nada).
• Replay manual pela tela ou por POST …/deliveries/{id}/replay/ (mesmo X-ProPartners-Delivery).

4. Boas práticas para o seu receptor

1. Valide o HMAC antes de qualquer coisa. Assinatura inválida: responda 401 e não processe.
2. Responda 2xx rápido e processe em fila do seu lado. O timeout é de 10 segundos.
3. Deduplique por X-ProPartners-Delivery (ou por event_id + a sua URL).
4. Ignore com 2xx o evento que você não conhece. Novos eventos podem surgir (quem assina "todos" os recebe automaticamente) e novos campos podem aparecer nos existentes: seja tolerante a campos a mais.
5. Valores monetários chegam como string decimal ("49.90"); datas em ISO 8601 (UTC).

5. Eventos do fornecedor

Nos eventos de contrato e comissão, partner é o id do vínculo do parceiro (o mesmo enrollment da API REST). Para detalhes, consulte a API com esses ids.

lead.created

O principal evento de prospecção. Traz o que você precisa para chamar o lead por WhatsApp ou e-mail.

Quem cadastra a indicação (o parceiro ou o próprio fornecedor) declara que a pessoa autorizou o contato e responde por essa declaração. Por isso o lead já nasce autorizado (AUTHORIZED), com telefone e e-mail, e o ProPartners não manda pedido de autorização ao indicado.

{
  "created_at": "2026-09-29T13:08:34.541103+00:00",
  "data": {
    "consent_status": "authorized",
    "contact_declaration": {
      "at": "2026-09-29T13:08:34.495549+00:00",
      "by": "parceiro:[email protected]"
    },
    "contact_release": "declaracao",
    "indicador": {
      "email": "[email protected]",
      "name": "Maria Indicadora",
      "phone": "11988887777",
      "referral_code": "Y9JQCMY0"
    },
    "lead": {
      "channels": [
        "whatsapp",
        "email"
      ],
      "created_at": "2026-09-29T13:08:34.495549+00:00",
      "email": "[email protected]",
      "id": "bdc3b01f…",
      "name": "João Silva",
      "phone": "11911112222"
    },
    "service": {
      "id": "01ccdd2c…",
      "name": "Endereço Fiscal Av. Paulista"
    },
    "status": "AUTHORIZED",
    "tenant": {
      "id": "e55df0ed…",
      "name": "ProCoworking São Paulo"
    }
  },
  "event": "lead.created",
  "event_id": "lead.created:bdc3b01f…"
}

• channels: whatsapp se o lead tem telefone, email se tem e-mail (vazio se o contato não estiver liberado).
• contact_release diz se você pode entrar em contato (LGPD):
• declaracao: o caso normal. Quem cadastrou declarou que o titular autorizou (contact_declaration: {by, at} diz quem e quando). No primeiro contato, diga que veio por indicação e ofereça a opção de não ser mais procurado.
• consentimento: o próprio titular autorizou (formulário público de indicação).
• recusado: o titular disse que não quer contato. Não entre em contato; email e phone vêm vazios.
• pendente: só em leads antigos, de antes de 29/09/2026, sem declaração. email e phone vêm vazios.
• consent_status: authorized (autorizado, pela declaração ou pelo titular), refused (recusou) ou pending (só leads antigos).

lead.consent

O titular respondeu sobre o contato: pela página de autorização (links enviados antes de 29/09/2026, onde ele ainda pode dizer que não quer contato) ou por registro via API (POST /api/v1/leads/{id}/consent/). Leads novos nascem autorizados e normalmente não geram este evento; o mais comum aqui é a recusa (answer: "refused"): pare de contatar. Mesmo conteúdo do lead.created, mais consent: {answer, at, source}.

{
  "created_at": "2026-09-29T13:08:34.556590+00:00",
  "data": {
    "consent": {
      "answer": "authorized",
      "at": "2026-09-29T13:08:34.551414+00:00",
      "source": "opt-in-lead"
    },
    "consent_status": "authorized",
    "contact_declaration": {
      "at": "2026-09-29T13:08:34.495549+00:00",
      "by": "parceiro:[email protected]"
    },
    "contact_release": "consentimento",
    "indicador": {
      "email": "[email protected]",
      "name": "Maria Indicadora",
      "phone": "11988887777",
      "referral_code": "Y9JQCMY0"
    },
    "lead": {
      "channels": [
        "whatsapp",
        "email"
      ],
      "created_at": "2026-09-29T13:08:34.495549+00:00",
      "email": "[email protected]",
      "id": "bdc3b01f…",
      "name": "João Silva",
      "phone": "11911112222"
    },
    "service": {
      "id": "01ccdd2c…",
      "name": "Endereço Fiscal Av. Paulista"
    },
    "status": "AUTHORIZED",
    "tenant": {
      "id": "e55df0ed…",
      "name": "ProCoworking São Paulo"
    }
  },
  "event": "lead.consent",
  "event_id": "lead.consent:bdc3b01f…:authorized"
}

lead.converted

{
  "created_at": "2026-09-29T13:08:34.670121+00:00",
  "data": {
    "consent_status": "authorized",
    "contact_declaration": {
      "at": "2026-09-29T13:08:34.495549+00:00",
      "by": "parceiro:[email protected]"
    },
    "contact_release": "consentimento",
    "contract": {
      "external_id": "CT-000123",
      "id": "73b2b794…"
    },
    "indicador": {
      "email": "[email protected]",
      "name": "Maria Indicadora",
      "phone": "11988887777",
      "referral_code": "Y9JQCMY0"
    },
    "lead": {
      "channels": [
        "whatsapp",
        "email"
      ],
      "created_at": "2026-09-29T13:08:34.495549+00:00",
      "email": "[email protected]",
      "id": "bdc3b01f…",
      "name": "João Silva",
      "phone": "11911112222"
    },
    "service": {
      "id": "01ccdd2c…",
      "name": "Endereço Fiscal Av. Paulista"
    },
    "status": "CONVERTED",
    "tenant": {
      "id": "e55df0ed…",
      "name": "ProCoworking São Paulo"
    }
  },
  "event": "lead.converted",
  "event_id": "lead.converted:bdc3b01f…"
}

contract.created

{
  "created_at": "2026-09-29T13:08:34.695253+00:00",
  "data": {
    "contract": "73b2b794…",
    "dispute": false,
    "partner": "8d34d8bd…"
  },
  "event": "contract.created",
  "event_id": "ba3b433e…"
}

dispute: true quando a pessoa do contrato tinha indicação em andamento de outro parceiro deste fornecedor: o contrato nasce marcado, as comissões dele ficam retidas e a sua equipe decide na Gestão (Contratos → Resolver) para qual parceiro vai. Veja a regra de indicação única em webhooks de entrada.

contract.cancelled

{
  "created_at": "2026-09-29T13:08:35.455335+00:00",
  "data": {
    "contract": "73b2b794…",
    "partner": "8d34d8bd…"
  },
  "event": "contract.cancelled",
  "event_id": "31792ce9…"
}

commission.created

{
  "created_at": "2026-09-29T13:08:34.767942+00:00",
  "data": {
    "amount": "49.90",
    "commission": "5546090e…",
    "partner": "8d34d8bd…"
  },
  "event": "commission.created",
  "event_id": "11d6c5b6…"
}

commission.reversed

status pode ser REVERSED (estorno ainda na carência: nada tinha sido pago) ou CLAWBACK (já pago: o valor é recuperado das próximas comissões do parceiro).

{
  "created_at": "2026-09-29T13:08:35.407134+00:00",
  "data": {
    "commission": "5546090e…",
    "partner": "8d34d8bd…",
    "status": "CLAWBACK"
  },
  "event": "commission.reversed",
  "event_id": "7c6e3294…"
}

pix.validation_requested

Disparado pelo botão Solicitar no checklist de análise do parceiro. A chave Pix vai mascarada: o seu sistema só precisa pedir ao parceiro que valide em validar_pix_url. Pode ser reenviado (sem deduplicação entre cliques).

{
  "created_at": "2026-09-29T13:08:35.375369+00:00",
  "data": {
    "affiliate": {
      "email": "[email protected]",
      "name": "Maria Indicadora",
      "phone": "11988887777",
      "pix_key_masked": "ma***om",
      "referral_code": "Y9JQCMY0"
    },
    "links": {
      "validar_pix_url": "https://dashboard.propartners.com.br/meus-dados/"
    },
    "service": {
      "id": "01ccdd2c…",
      "name": "Endereço Fiscal Av. Paulista"
    },
    "tenant": {
      "id": "e55df0ed…",
      "name": "ProCoworking São Paulo"
    },
    "validation": {
      "requested_at": "2026-09-29T13:08:35.373007+00:00",
      "status": "requested"
    }
  },
  "event": "pix.validation_requested",
  "event_id": "c1cde878…"
}

notify.message

É assim que o ProPartners conversa com os seus parceiros e leads através do SEU sistema. Cada aviso de relacionamento (cadastro recebido, adesão aprovada, lead novo, contrato fechado, comissão confirmada, Pix enviado, pedido de validação de Pix…) chega como um notify.message com o texto pronto. O seu sistema escolhe o canal (WhatsApp, e-mail, outro), entrega e guarda o histórico. O ProPartners não fala direto com WhatsApp.

{
  "created_at": "2026-09-29T13:08:34.635395+00:00",
  "data": {
    "attachments": [],
    "audience": "partner",
    "channels": [
      "whatsapp",
      "email"
    ],
    "context": {
      "affiliate": {
        "id": "e1dcbac6…",
        "name": "Maria Indicadora"
      },
      "enrollment": {
        "id": "8d34d8bd…",
        "referral_code": "Y9JQCMY0",
        "status": "APPROVED"
      },
      "service": {
        "id": "01ccdd2c…",
        "name": "Endereço Fiscal Av. Paulista"
      }
    },
    "email_sent_by_propartners": true,
    "message": "Parabéns, Maria Indicadora! O contrato de João ••• em Endereço Fiscal Av. Paulista foi fechado (ref. CT-000123).\n\nA partir de agora, a cada pagamento confirmado desse cliente a sua comissão é gerada, conforme o termo de parceria do serviço.\n\nAcompanhe seus contratos e comissões no painel: https://dashboard.propartners.com.br/painel/",
    "message_chat": "Parabéns, Maria Indicadora! O contrato de João ••• em Endereço Fiscal Av. Paulista foi fechado (ref. CT-000123).\n\nA partir de agora, a cada pagamento confirmado desse cliente a sua comissão é gerada, conforme o termo de parceria do serviço.\n\nAcompanhe seus contratos e comissões no painel: https://dashboard.propartners.com.br/painel/",
    "notification": "contract.activated",
    "subject": "Contrato fechado: João •••",
    "tenant": {
      "id": "e55df0ed…",
      "name": "ProCoworking São Paulo"
    },
    "to": {
      "email": "[email protected]",
      "name": "Maria Indicadora",
      "phone": "11988887777",
      "phone_e164": "+5511988887777"
    }
  },
  "event": "notify.message",
  "event_id": "notify:contract.activated:73b2b794…"
}

Valores de notification (novos podem surgir: trate os desconhecidos entregando message_chat/message normalmente):

E-mail direto do ProPartners. Por padrão o ProPartners também envia esses avisos por e-mail. Se o seu sistema já faz a entrega completa, desmarque "Disparar notificações a parceiros e leads por e-mail" em Minha Conta: a partir daí o e-mail só sai por você (email_sent_by_propartners: false). Se nenhum endpoint ativo estiver recebendo notify.message, o ProPartners continua enviando por e-mail mesmo com a opção desmarcada, para nenhum aviso se perder. E-mails de sistema (código de acesso, redefinição de senha) e os documentos anexos sempre saem direto do ProPartners.

lead.welcome: boas-vindas ao indicado

Quando uma indicação nasce (API do fornecedor, Gestão, painel do parceiro ou formulário público) com telefone válido e contato liberado (contact_release = declaracao ou consentimento; nunca pendente/recusado), o ProPartners emite um notify.message com audience: "lead" e o texto pronto do primeiro contato. O seu sistema entrega no WhatsApp e segue o atendimento quando a pessoa responder. Um por lead (event_id notify:lead.welcome:<lead_id>): edição do lead não reemite. Sai antes do lead.created do mesmo lead. Não vai por e-mail (to.email vazio, channels: ["whatsapp"], email_sent_by_propartners: false).

{
  "notification": "lead.welcome",
  "audience": "lead",
  "channels": ["whatsapp"],
  "to": {"name": "Izabela Feitosa", "email": "", "phone": "11988776655", "phone_e164": "+5511988776655"},
  "message_chat": "Olá, Izabela! Tudo bem? Aqui é do time de Parcerias da ProCoworking Alphaville.\nCarlos Parceiro indicou você para conhecer Endereço Fiscal Alphaville e pediu que a gente entrasse em contato. Como posso te ajudar?",
  "email_sent_by_propartners": false,
  "context": {
    "affiliate": {"id": "e1dcbac6…", "name": "Carlos Parceiro", "referral_code": "AACCDKDD"},
    "enrollment": {"id": "8d34d8bd…"},
    "lead": {"id": "5f0c1a2b…", "name": "Izabela Feitosa", "phone": "+5511988776655"},
    "service": {"id": "4d182bcf…", "name": "Endereço Fiscal Alphaville"},
    "supplier": {"id": "b5c3690e…", "name": "ProCoworking Alphaville"}
  }
}

(trecho de data; os demais campos do notify.message também vêm.) O texto é editável por fornecedor no modelo de notificação lead.welcome, com {lead_primeiro_nome}, {parceiro_nome}, {servico_nome} e {unidade_nome} (a unidade é sempre a do fornecedor em que o lead nasceu). Sem nome, a saudação vira "Olá!". O texto não traz preço, código de indicação, ids nem link.

webhook.test

{
  "created_at": "2026-09-29T13:08:35.458198+00:00",
  "data": {
    "endpoint": {
      "id": "4ada71d0…",
      "label": ""
    },
    "message": "Teste de webhook do ProPartners. Se chegou, a integração está funcionando."
  },
  "event": "webhook.test",
  "event_id": "5bdb8534…"
}

6. Eventos do parceiro

Todo evento do parceiro traz tenant, service e enrollment {id, referral_code}. O nome do cliente vai mascarado, salvo se o fornecedor liberou o nome completo.

lead.created (parceiro)

{
  "created_at": "2026-09-29T13:08:34.548562+00:00",
  "data": {
    "consent_status": "authorized",
    "enrollment": {
      "id": "8d34d8bd…",
      "referral_code": "Y9JQCMY0"
    },
    "lead": {
      "created_at": "2026-09-29T13:08:34.495549+00:00",
      "id": "bdc3b01f…",
      "name": "João •••"
    },
    "service": {
      "id": "01ccdd2c…",
      "name": "Endereço Fiscal Av. Paulista"
    },
    "status": "AUTHORIZED",
    "tenant": {
      "id": "e55df0ed…",
      "name": "ProCoworking São Paulo"
    }
  },
  "event": "lead.created",
  "event_id": "lead.created:bdc3b01f…"
}

lead.consent (parceiro)

{
  "created_at": "2026-09-29T13:08:34.563377+00:00",
  "data": {
    "consent": {
      "answer": "authorized",
      "at": "2026-09-29T13:08:34.551414+00:00"
    },
    "consent_status": "authorized",
    "enrollment": {
      "id": "8d34d8bd…",
      "referral_code": "Y9JQCMY0"
    },
    "lead": {
      "created_at": "2026-09-29T13:08:34.495549+00:00",
      "id": "bdc3b01f…",
      "name": "João •••"
    },
    "service": {
      "id": "01ccdd2c…",
      "name": "Endereço Fiscal Av. Paulista"
    },
    "status": "AUTHORIZED",
    "tenant": {
      "id": "e55df0ed…",
      "name": "ProCoworking São Paulo"
    }
  },
  "event": "lead.consent",
  "event_id": "lead.consent:bdc3b01f…:authorized"
}

lead.converted (parceiro)

{
  "created_at": "2026-09-29T13:08:34.681414+00:00",
  "data": {
    "consent_status": "authorized",
    "contract": {
      "external_id": "CT-000123",
      "id": "73b2b794…"
    },
    "enrollment": {
      "id": "8d34d8bd…",
      "referral_code": "Y9JQCMY0"
    },
    "lead": {
      "created_at": "2026-09-29T13:08:34.495549+00:00",
      "id": "bdc3b01f…",
      "name": "João •••"
    },
    "service": {
      "id": "01ccdd2c…",
      "name": "Endereço Fiscal Av. Paulista"
    },
    "status": "CONVERTED",
    "tenant": {
      "id": "e55df0ed…",
      "name": "ProCoworking São Paulo"
    }
  },
  "event": "lead.converted",
  "event_id": "lead.converted:bdc3b01f…"
}

contract.activated

{
  "created_at": "2026-09-29T13:08:34.643701+00:00",
  "data": {
    "contract": {
      "customer_name": "João •••",
      "external_id": "CT-000123",
      "id": "73b2b794…",
      "started_at": "2026-09-29",
      "status": "ACTIVE"
    },
    "enrollment": {
      "id": "8d34d8bd…",
      "referral_code": "Y9JQCMY0"
    },
    "service": {
      "id": "01ccdd2c…",
      "name": "Endereço Fiscal Av. Paulista"
    },
    "tenant": {
      "id": "e55df0ed…",
      "name": "ProCoworking São Paulo"
    }
  },
  "event": "contract.activated",
  "event_id": "contract.activated:73b2b794…"
}

contract.cancelled (parceiro)

{
  "created_at": "2026-09-29T13:08:35.449469+00:00",
  "data": {
    "contract": {
      "customer_name": "João •••",
      "external_id": "CT-000123",
      "id": "73b2b794…",
      "started_at": "2026-09-29",
      "status": "CANCELLED"
    },
    "enrollment": {
      "id": "8d34d8bd…",
      "referral_code": "Y9JQCMY0"
    },
    "reason": "cliente encerrou o contrato",
    "service": {
      "id": "01ccdd2c…",
      "name": "Endereço Fiscal Av. Paulista"
    },
    "tenant": {
      "id": "e55df0ed…",
      "name": "ProCoworking São Paulo"
    }
  },
  "event": "contract.cancelled",
  "event_id": "contract.cancelled:73b2b794…"
}

commission.confirmed

Cortesia e comissão zero não geram este evento.

{
  "created_at": "2026-09-29T13:08:34.748387+00:00",
  "data": {
    "commission": {
      "amount": "49.90",
      "competence": "2026-09-01",
      "id": "5546090e…",
      "status": "CONFIRMED"
    },
    "contract": {
      "customer_name": "João •••",
      "external_id": "CT-000123",
      "id": "73b2b794…",
      "started_at": "2026-09-29",
      "status": "ACTIVE"
    },
    "enrollment": {
      "id": "8d34d8bd…",
      "referral_code": "Y9JQCMY0"
    },
    "service": {
      "id": "01ccdd2c…",
      "name": "Endereço Fiscal Av. Paulista"
    },
    "tenant": {
      "id": "e55df0ed…",
      "name": "ProCoworking São Paulo"
    }
  },
  "event": "commission.confirmed",
  "event_id": "commission.confirmed:5546090e…"
}

payout.paid

Desde 30/10/2026 o repasse sai em um Pix por contrato: um evento payout.paid por transferência, com payout.contract_external_id dizendo qual contrato aquele Pix pagou (vazio em pagamentos antigos consolidados ou em saldo avulso). pix_validation_discount: centavos do micro-depósito de validação da chave Pix, descontados no primeiro pagamento.

{
  "created_at": "2026-09-29T13:08:34.867151+00:00",
  "data": {
    "commissions": [
      {
        "amount": "49.90",
        "competence": "2026-09-01",
        "contract_external_id": "CT-000123",
        "id": "5546090e…"
      }
    ],
    "enrollment": {
      "id": "8d34d8bd…",
      "referral_code": "Y9JQCMY0"
    },
    "payout": {
      "amount": "49.90",
      "batch": "9604b92f…",
      "contract_external_id": "CT-000123",
      "e2e_id": "E-MOCK-b0a231175120453b98",
      "id": "894f25b5…",
      "pix_validation_discount": "0"
    },
    "service": {
      "id": "01ccdd2c…",
      "name": "Endereço Fiscal Av. Paulista"
    },
    "tenant": {
      "id": "e55df0ed…",
      "name": "ProCoworking São Paulo"
    }
  },
  "event": "payout.paid",
  "event_id": "payout.paid:894f25b5…"
}