user_created

This event fires every time a user appears in the tenant for the first time, regardless of the source channel. It’s the ideal trigger to provision the new user into external systems (CRM, marketing, billing).

The internal event name (used when subscribing webhooks in the Console) is user_created.

Point a listener at your URL with EventName: "user_created". Auth, secret and signature verification are covered in Subscribing and verifying 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://myapp.com/webhooks/cativa",
    "IsActive": true
  }'

When it fires

User signs up through the community’s public form
Admin creates the user manually in the dashboard
User signs in for the first time via SSO (Google, Apple, OIDC)
Bulk import creates the user
You create the user via API

When it does NOT fire

Login of an existing user (no creation happens)
Profile update (name, email, phone)
Reactivation of a soft-deleted user (the user already existed)
Creation fails (validation, duplicate email, etc.)
User not found while enriching the payload (delivery is skipped)

Payload

The payload is serialized in PascalCase and delivered in the body of the POST with Content-Type: application/json:

{
  "CustomerId": "01HQ0ABCDEF1234567890XYZ",
  "UserId": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
  "Email": "mary@example.com",
  "FirstName": "Mary",
  "LastName": "Smith",
  "DisplayName": "Mary Smith",
  "Username": "mary.smith",
  "PhoneNumber": "+15551234567",
  "CreatedAt": "2026-05-08T14:32:01Z",
  "User": {
    "Id": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
    "Email": "mary@example.com",
    "FirstName": "Mary",
    "LastName": "Smith",
    "DisplayName": "Mary Smith",
    "Username": "mary.smith",
    "PhoneNumber": "+15551234567",
    "CreatedAt": "2026-05-08T14:32:01Z",
    "BadgeId": null,
    "Badges": []
  }
}

The top-level fields (UserId, Email, FirstName, …) and the nested User object exist side by side to keep parity with v1 of the platform. We recommend consuming the nested User object in new code — it has the same shape as other events (user_joined_group, user_received_badge, etc.) and simplifies generic handlers.

Payload fields

Field	Type	Description
`CustomerId`	GUID	ID of the tenant that emitted the event. Use it to route when your endpoint receives webhooks from multiple tenants.
`UserId`	GUID	ID of the user created (equals `User.Id`).
`Email`	string	User email (equals `User.Email`).
`FirstName`	string	First name.
`LastName`	string	Last name.
`DisplayName`	string	Display name.
`Username`	string	Username (no spaces).
`PhoneNumber`	string	Phone, when provided.
`CreatedAt`	ISO 8601	When the user was created in the tenant.
`User.Id`	GUID	User ID (mirror of `UserId`).
`User.Email`	string	Email (mirror of `Email`).
`User.FirstName`	string	First name.
`User.LastName`	string	Last name.
`User.DisplayName`	string	Display name.
`User.Username`	string	Username.
`User.PhoneNumber`	string	Phone.
`User.CreatedAt`	ISO 8601	Same value as `CreatedAt`.
`User.BadgeId`	GUID \| null	Primary badge — for `user_created` this will almost always be `null`, since the user has no badges yet.
`User.Badges`	GUID[]	List of badges assigned to the user. For `user_created` this is usually `[]`.

Request headers

Header	Description
`X-Cativa-Signature`	HMAC-SHA256 signature of the delivery, in the format `t=<unixTs>,v1=<hex>`. Verify it before processing the event.
`X-Cativa-Idempotency-Key`	Canonical deduplication key. Identical across all retries of the same delivery.
`X-Cativa-Execution-Id`	Unique ID of this event. Stable across retries — use it as your idempotency key.
`X-Cativa-Automation-Id`	ID of the listener configured in the Console (same value across all deliveries from the same subscription).

The full explanation of how to verify X-Cativa-Signature, handle retries and ensure idempotency (with examples in Node, Python, Go and C#) lives in Subscribing and verifying webhooks.

Use cases

Provision in your CRM — create a contact in HubSpot/Pipedrive/Salesforce with Email, FirstName, LastName and a CustomerId tag for cross-tenant segmentation.
Email onboarding — kick off a welcome sequence in your email provider (Mailchimp, Customer.io, ActiveCampaign) using the Email you just received.
Sync with billing — create the matching customer in Stripe/Asaas or in your own internal system, even before the first payment.

Reacting to the event

After verifying the HMAC signature, provision the new user in your CRM. The example does an idempotent upsert by UserId and tags the source tenant 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}`], // cross-tenant segmentation
  });
}

user_joined_group

Fired when the user joins a group in the community.

user_received_badge

Fired when the user earns a badge (purchase, manual assignment or automation).

Subscribing to webhooks

How to register listeners, verify HMAC and handle retries.

Webhooks (overview)

Why webhooks, delivery guarantees and payload format.

Get Started

Concepts

Guides

Webhooks

Changelog

When it fires

When it does NOT fire

Payload

Payload fields

Request headers

Use cases

Reacting to the event

user_joined_group

user_received_badge

Subscribing to webhooks

Webhooks (overview)

​Subscribe to this event

​When it fires

​When it does NOT fire

​Payload

​Payload fields

​Request headers

​Use cases

​Reacting to the event

​Related events

user_joined_group

user_received_badge

Subscribing to webhooks

Webhooks (overview)

Subscribe to this event

When it fires

When it does NOT fire

Payload

Payload fields

Request headers

Use cases

Reacting to the event

Related events