Como mandar eventos dos seus sistemas para a ficha do cliente

Um webhook é uma chamada automática que um sistema faz para outro quando algo acontece: uma conta foi criada, um pagamento foi confirmado, uma aula foi concluída. Quem recebe guarda o aviso e decide o que fazer com ele. O People recebe esses avisos de qualquer sistema que os envie, desde que assinados, e os transforma na ficha de cada pessoa.

Por que assinar a chamada

Um endereço público que recebe dados pode ser chamado por qualquer pessoa que o descubra. Sem uma prova, o receptor não tem como saber se o aviso veio do seu sistema ou de alguém que forjou uma mensagem para inventar um cliente. A assinatura resolve isso com um segredo compartilhado entre a fonte e o People.

O mecanismo é o HMAC-SHA256: a fonte calcula uma assinatura sobre o identificador da entrega, o carimbo de tempo e o corpo, usando o segredo. O People recalcula a mesma conta e compara. Se qualquer parte mudou, a comparação falha e a entrega é recusada com 401. Isso protege de duas coisas: quem não conhece o segredo não consegue enviar eventos, e um corpo interceptado no caminho não pode ser alterado sem invalidar a assinatura.

O People segue o padrão Standard Webhooks, com cabeçalhos prefixados por x-ccm (para integrações abertas, qualquer sistema que assine a entrega entra):

O carimbo de tempo precisa estar dentro de 5 minutos do relógio do servidor. Isso impede que uma chamada antiga seja reenviada depois como se fosse nova.

Como montar a assinatura

A chave do HMAC é o segredo sem o prefixo whsec_, decodificado de base64. A assinatura é calculada sobre a string id.timestamp.corpo, exatamente como o corpo foi enviado. Serializar o JSON duas vezes pode mudar os bytes, e aí a assinatura não confere.

import { createHmac, randomUUID } from 'node:crypto'

const id = randomUUID()
const timestamp = Math.floor(Date.now() / 1000)
const body = JSON.stringify({
    type: 'account.created',
    timestamp: new Date().toISOString(),
    data: { person: { email: 'ana@escola.exemplo', name: 'Ana Souza' } },
})
const key = Buffer.from(process.env.PEOPLE_SECRET.replace(/^whsec_/, ''), 'base64')
const signature = createHmac('sha256', key).update(`${id}.${timestamp}.${body}`).digest('base64')

await fetch(process.env.PEOPLE_SOURCE_URL, {
    method: 'POST',
    headers: {
        'content-type': 'application/json',
        'x-ccm-id': id,
        'x-ccm-timestamp': String(timestamp),
        'x-ccm-signature': `v1,${signature}`,
    },
    body,
})

O endereço PEOPLE_SOURCE_URL é o da fonte criada no painel, e o segredo PEOPLE_SECRET aparece uma única vez, na criação. Guarde os dois como variáveis de ambiente, não no código.

O que acontece quando o evento chega

O caminho é curto e acontece em uma única chamada:

1. Confere a assinatura. Cabeçalhos presentes, carimbo dentro da janela, assinatura igual à recalculada. Falhou, responde 401 com a mensagem do que corrigir.

2. Confere o id. Se aquele x-ccm-id já foi recebido, a entrega é tratada como reenvio: responde 200 com duplicates: 1 e nada é gravado de novo. Isso permite reenviar sem medo.

3. Procura a pessoa. O evento se junta a uma ficha por identidade igual, como um e-mail verificado pela fonte ou o id da pessoa no seu sistema. Se a identidade aponta para duas fichas, o evento vai para a mais forte, e o caso vira uma sugestão de fusão. Duas fichas nunca se fundem sozinhas; juntar é uma ação que pede confirmação.

4. Recalcula o estágio. Lead, prospect e customer saem do que a pessoa fez. Um pagamento confirmado é o que leva à condição de customer; um cancelamento depois disso volta a prospect.

5. Responde com o resultado. A resposta traz o id do evento, a pessoa, o estágio e se houve tradução, para você conferir na sua própria tela.

Um evento de teste, com o tipo terminado em .test, só confere a assinatura e responde 200 com test: true e accepted: 0, sem gravar nada. É o jeito seguro de checar a integração antes do primeiro evento real.

Vocabulário: quem decide o nome do evento

O tipo do evento é o que o seu sistema manda, em minúsculas e separado por ponto (aula.concluida). Se o nome não é um dos que o People já conhece, ele é guardado como chegou e aparece na fonte como "a traduzir". Nada é descartado: você escreve a tradução na própria fonte e o People relê o que já tinha chegado. Os tipos que mexem no estágio (account.created, account.activated, subscription.paid, subscription.canceled) são os que importam para acertar o funil; subscription.paid é o único caminho para customer.

Perguntas frequentes

Preciso de uma biblioteca para assinar?

Não. A assinatura é um HMAC-SHA256 comum, presente em qualquer linguagem. Bibliotecas de Standard Webhooks ajudam, mas o trecho acima é tudo o que é preciso.

O que acontece se o meu relógio estiver adiantado?

Se o carimbo de tempo sair da janela de 5 minutos do servidor, a chamada é recusada com 401 dizendo que o timestamp está fora da janela. Use o relógio do servidor que faz a chamada, sincronizado por NTP.

Posso trocar o segredo sem parar a integração?

Pode. Ao rotacionar, o segredo anterior continua valendo por 24 horas. Durante esse intervalo, o People aceita assinaturas feitas com qualquer um dos dois, e você troca no seu sistema sem perder eventos.

Para continuar lendo

• Lead, prospect e cliente: a diferença e como saber o estágio de cada pessoa

• A ficha de cada cliente, do primeiro toque ao pagamento

• Quando o lead vira cliente: estágio derivado do que a pessoa fez

Quem recebe o aviso e o que ele faz

Quando o evento entra, a ficha da pessoa ganha uma linha no histórico com o que aconteceu e quando. Os agentes do People leem essa linha junto com o resto da ficha para propor o próximo passo. Propor não é enviar: toda mensagem à pessoa passa pela checagem sem IA e, quando é falar com ela, pela aprovação de quem assina; a primeira mensagem e a oferta de preço são sempre aprovadas por uma pessoa. Para ver isso na sua conta: Conhecer o People.

<reasoning_effort>8</reasoning_effort>

Fontes

• Referência do People para pessoas e agentes (llms.txt)

• Página do People