user_created

Esse evento é disparado toda vez que um usuário aparece pela primeira vez no tenant, independente do canal de origem. É o gatilho ideal para provisionar o novo usuário em sistemas externos (CRM, marketing, billing).

O nome interno do evento (usado nos cadastros de webhook do Console) é user_created.

Assinar este evento

Aponte um listener para a sua URL informando EventName: "user_created". Auth, secret e verificação da assinatura estão em Cadastrando e verificando webhooks.

curl -X POST \
  https://apis.cativalab.digital/tenant/api/v2/admin/integration/01HQ0ABCDEF1234567890XYZ/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "EventName": "user_created",
    "Url": "https://meuapp.com/webhooks/cativa",
    "IsActive": true
  }'

Quando dispara

Usuário se cadastra pelo formulário público da comunidade
Admin cria o usuário manualmente no painel
Usuário entra pela primeira vez via SSO (Google, Apple, OIDC)
Importação em lote (bulk import) cria o usuário
Você cria o usuário via API

Quando NÃO dispara

Login de usuário já existente (não há criação)
Atualização de perfil (nome, email, telefone)
Reativação de usuário soft-deleted (o usuário já existia)
Falha na criação (validação, email duplicado, etc.)
Usuário não encontrado no enriquecimento do payload (entrega é pulada)

Payload

O payload é serializado em PascalCase e enviado no body do POST com Content-Type: application/json:

{
  "CustomerId": "01HQ0ABCDEF1234567890XYZ",
  "UserId": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
  "Email": "maria@exemplo.com",
  "FirstName": "Maria",
  "LastName": "Silva",
  "DisplayName": "Maria Silva",
  "Username": "maria.silva",
  "PhoneNumber": "+5511999998888",
  "CreatedAt": "2026-05-08T14:32:01Z",
  "User": {
    "Id": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
    "Email": "maria@exemplo.com",
    "FirstName": "Maria",
    "LastName": "Silva",
    "DisplayName": "Maria Silva",
    "Username": "maria.silva",
    "PhoneNumber": "+5511999998888",
    "CreatedAt": "2026-05-08T14:32:01Z",
    "BadgeId": null,
    "Badges": []
  }
}

Os campos do nível raiz (UserId, Email, FirstName, …) e o objeto User aninhado existem lado a lado para manter paridade com a v1 da plataforma. Recomendamos consumir o objeto User aninhado em código novo, ele tem o mesmo shape de outros eventos (user_joined_group, user_received_badge, etc.) e simplifica handlers genéricos.

Campos do payload

Campo	Tipo	Descrição
`CustomerId`	GUID	ID do tenant que originou o evento. Use para rotear quando seu endpoint recebe webhooks de múltiplos tenants.
`UserId`	GUID	ID do usuário criado (igual a `User.Id`).
`Email`	string	Email do usuário (igual a `User.Email`).
`FirstName`	string	Primeiro nome.
`LastName`	string	Sobrenome.
`DisplayName`	string	Nome de exibição.
`Username`	string	Nome de usuário (sem espaços).
`PhoneNumber`	string	Telefone, quando informado.
`CreatedAt`	ISO 8601	Quando o usuário foi criado no tenant.
`User.Id`	GUID	ID do usuário (espelho de `UserId`).
`User.Email`	string	Email (espelho de `Email`).
`User.FirstName`	string	Primeiro nome.
`User.LastName`	string	Sobrenome.
`User.DisplayName`	string	Nome de exibição.
`User.Username`	string	Nome de usuário.
`User.PhoneNumber`	string	Telefone.
`User.CreatedAt`	ISO 8601	Mesmo valor de `CreatedAt`.
`User.BadgeId`	GUID \| null	Badge principal, em `user_created` virá quase sempre `null`, já que o usuário ainda não tem badges.
`User.Badges`	GUID[]	Lista de badges atribuídos ao usuário. Em `user_created` geralmente é `[]`.

Headers do request

Header	Descrição
`X-Cativa-Signature`	Assinatura HMAC-SHA256 do disparo, no formato `t=<unixTs>,v1=<hex>`. Verifique antes de processar o evento.
`X-Cativa-Idempotency-Key`	Chave canônica de deduplicação. Igual em todos os retries da mesma entrega.
`X-Cativa-Execution-Id`	ID único deste evento. Estável entre retries, use como chave de idempotência.
`X-Cativa-Automation-Id`	ID do listener configurado no Console (mesmo valor para todos os disparos do mesmo cadastro).

A explicação completa de como verificar X-Cativa-Signature, lidar com retries e garantir idempotência (com exemplos em Node, Python, Go e C#) está em Cadastrando e verificando webhooks.

Casos de uso

Provisionar no CRM, criar contato no HubSpot/Pipedrive/Salesforce com Email, FirstName, LastName e tag do CustomerId para segmentação cross-tenant.
Onboarding por email, disparar uma sequência de boas-vindas no seu provedor de email (Mailchimp, Customer.io, ActiveCampaign) usando o Email recém-recebido.
Sincronizar com billing, criar o customer correspondente no Stripe/Asaas ou no seu próprio sistema interno, mesmo antes do primeiro pagamento.

Reagindo ao evento

Depois de verificar a assinatura HMAC, provisione o novo usuário no seu CRM. O exemplo faz um upsert idempotente pelo UserId e marca o tenant de origem via CustomerId:

async function onUserCreated(event) {
  const { UserId, Email, FirstName, LastName, CustomerId } = event;

  await crm.contacts.upsert({
    externalId: UserId,
    email: Email,
    firstName: FirstName,
    lastName: LastName,
    tags: [`cativa:${CustomerId}`], // segmentação cross-tenant
  });
}

Eventos relacionados

user_joined_group

Disparado quando o usuário entra num grupo da comunidade.

user_received_badge

Disparado quando o usuário ganha um badge (compra, atribuição manual ou automação).

Cadastrando webhooks

Como cadastrar listeners, verificar HMAC e lidar com retries.

Webhooks (visão geral)

Por que webhooks, garantias de entrega e formato dos payloads.

Comece aqui

Conceitos

Guias

Webhooks

Changelog

Assinar este evento

Quando dispara

Quando NÃO dispara

Payload

Campos do payload

Headers do request

Casos de uso

Reagindo ao evento

Eventos relacionados

user_joined_group

user_received_badge

Cadastrando webhooks

Webhooks (visão geral)

​Assinar este evento

​Quando dispara

​Quando NÃO dispara

​Payload

​Campos do payload

​Headers do request

​Casos de uso

​Reagindo ao evento

​Eventos relacionados

user_joined_group

user_received_badge

Cadastrando webhooks

Webhooks (visão geral)

Assinar este evento

Quando dispara

Quando NÃO dispara

Payload

Campos do payload

Headers do request

Casos de uso

Reagindo ao evento

Eventos relacionados