paywall_payment_completed

This event fires as soon as the payment gateway (Asaas, Stripe, etc.) confirms a paywall payment. It’s the canonical moment to sync access in external systems (legacy member area, course platform, ERP), since internally Cativa also uses this same event to grant the user a badge/group/course.

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

Point a listener at your URL with EventName: "paywall_payment_completed". Auth, secret and verification 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": "paywall_payment_completed",
    "Url": "https://myapp.com/webhooks/cativa",
    "IsActive": true
  }'

When it fires

Payment gateway (Asaas, Stripe) sends the confirmation callback to Cativa
A PIX payment clears
A boleto charge clears
A credit-card charge is captured successfully
A manual payment is marked as confirmed in the admin

When it does NOT fire

Payment created but still pending (PIX generated and not paid, boleto not yet due, etc.)
Payment failed or cancelled by the gateway
Payment refunded after it had been confirmed
Payment without a resolved UserId (e.g. PIX where the payer hasn’t been associated with a tenant user yet) — delivery is skipped
Paywall or payment 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. The payload has three nested objects — User, Paywall and Payment:

{
  "CustomerId": "01HQ0ABCDEF1234567890XYZ",
  "User": {
    "Id": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
    "Email": "mary@example.com",
    "FirstName": "Mary",
    "LastName": "Smith",
    "DisplayName": "Mary Smith",
    "Username": "mary.smith",
    "CreatedAt": "2026-04-12T14:32:01Z"
  },
  "Paywall": {
    "Id": "01HQ5PAYWALL1234567890ABC",
    "Name": "Premium Mentorship 2026",
    "Description": "12 months of access to mentorship, exclusive courses and the VIP group.",
    "CustomLink": "premium-mentorship-2026",
    "FullUrl": "https://community.example.com/pagamento/premium-mentorship-2026",
    "Price": 1497.00,
    "DiscountPercentage": 10,
    "MaxInstallments": 12,
    "AccessMonths": 12,
    "RemoveAfterExpiration": true,
    "ActionType": 5,
    "ActionPayload": "01HQ4ABCDEF1234567890XYZ",
    "ImageUrl": "https://cdn.cativalab.digital/paywall/01HQ5.../cover.jpg",
    "OpeningLink": "https://community.example.com/welcome-mentorship"
  },
  "Payment": {
    "PaymentId": "01HQ9PAYMENT1234567890XYZ",
    "ValorPago": 1347.30,
    "ValorOriginal": 1497.00,
    "Desconto": 10,
    "Installments": 12,
    "TipoPagamento": "CREDIT_CARD",
    "Gateway": "Asaas",
    "IdTransacao": "pay_5478392a01b2c3d4e5f6",
    "CompletedAt": "2026-05-08T14:32:01Z"
  }
}

Payload fields

Root

Field	Type	Description
`CustomerId`	GUID	ID of the tenant that emitted the event.
`User`	object	Buyer information.
`Paywall`	object	Configuration of the paywall that was paid.
`Payment`	object	Details of the confirmed payment.

`User`

Field	Type	Description
`User.Id`	GUID	ID of the buyer.
`User.Email`	string	Buyer email.
`User.FirstName`	string	First name.
`User.LastName`	string	Last name.
`User.DisplayName`	string	Display name.
`User.Username`	string	Username.
`User.CreatedAt`	ISO 8601	When the user was created in the tenant.

`Paywall`

Field	Type	Description
`Paywall.Id`	GUID	Paywall ID.
`Paywall.Name`	string	Configured name of the paywall.
`Paywall.Description`	string \| null	Free-text description, when provided.
`Paywall.CustomLink`	string	Slug used in the public paywall URL.
`Paywall.FullUrl`	string \| null	Full public checkout URL (`{tenant-origin}/pagamento/{CustomLink}`). `null` when the tenant has no origin configured.
`Paywall.Price`	decimal	Configured full price (in the tenant’s currency — usually BRL).
`Paywall.DiscountPercentage`	int	Discount percentage active on the paywall (0-100).
`Paywall.MaxInstallments`	int	Maximum number of installments allowed by the paywall.
`Paywall.AccessMonths`	int \| null	Number of months of access granted by the purchase. `null` for lifetime access.
`Paywall.RemoveAfterExpiration`	bool	If `true`, access is automatically removed when `AccessMonths` expires.
`Paywall.ActionType`	int	Action executed after payment (see table below).
`Paywall.ActionPayload`	string \| null	Payload tied to `ActionType` — typically an ID (badge, course or group) or JSON, depending on the type.
`Paywall.ImageUrl`	string \| null	Cover image of the paywall, when configured.
`Paywall.OpeningLink`	string \| null	Link the user is redirected to after purchase, when configured.

Paywall.ActionType follows the enum:

Value	Meaning	`ActionPayload`
`0`	`CreateUserOnly` — only registers the user, no access granted	empty
`1`	`AddToCourse` — enrolls in a course	`CourseId` (GUID)
`2`	`GrantBadge` — assigns a badge	`BadgeId` (GUID)
`3`	`AddToGroup` — adds to a group	`GroupId` (GUID)
`4`	`AddToCourseAndGrantBadge`	JSON with `CourseId` + `BadgeId`
`5`	`AddToGroupAndGrantBadge`	JSON with `GroupId` + `BadgeId`
`6`	`None` — no automatic action	empty

`Payment`

Field	Type	Description
`Payment.PaymentId`	GUID	ID of the confirmed payment.
`Payment.ValorPago`	decimal	Amount actually paid after discounts.
`Payment.ValorOriginal`	decimal	Full paywall price before discounts.
`Payment.Desconto`	int	Discount percentage applied to this payment (0-100).
`Payment.Installments`	int	Number of installments chosen by the buyer.
`Payment.TipoPagamento`	string	Payment method — typical values: `PIX`, `CREDIT_CARD`, `BOLETO`. Normalized to uppercase.
`Payment.Gateway`	string	Gateway that processed the payment (e.g. `Asaas`, `Stripe`). Empty string if not provided.
`Payment.IdTransacao`	string	External transaction ID at the gateway (use it for reconciliation). Empty string if not provided.
`Payment.CompletedAt`	ISO 8601	Moment when the payment was confirmed.

The Portuguese-named fields (ValorPago, ValorOriginal, Desconto, TipoPagamento, IdTransacao) are inherited from v1 of the platform and kept for compatibility with existing Make/Zapier integrations. They will not be renamed.

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

Grant access in an external platform — if you still host part of the content outside Cativa (legacy member area, Hotmart, Memberkit), use Payment.PaymentId + User.Id to provision access there as soon as the payment is confirmed.
Financial reconciliation — record Payment.IdTransacao + Payment.Gateway + Payment.ValorPago in your ERP/accounting to close the books per gateway.
Send a transactional email — fire a receipt, invoice or “purchase confirmed” welcome message using User.Email, Paywall.Name, Payment.ValorPago and Payment.Installments.

This event fires once per confirmed payment — it does not fire on automatic subscription renewal (recurring billing is not yet in production). Don’t treat this event as a renewal trigger.

Reacting to the event

After verifying the signature, grant access in your external platform. Payment.PaymentId is unique per confirmed payment, so it doubles as the idempotency key. Paywall.ActionType tells you what the purchase grants (see the enum table above):

async function onPaywallPaymentCompleted(event) {
  const { User, Paywall, Payment } = event;

  // Idempotency: already granted this payment? Bail out.
  if (await db.grants.exists(Payment.PaymentId)) return;

  // ActionType 5 = AddToGroupAndGrantBadge
  if (Paywall.ActionType === 5) {
    await externalPlatform.grantAccess({
      userEmail: User.Email,
      product: Paywall.Name,
      months: Paywall.AccessMonths, // null = lifetime access
    });
  }

  await db.grants.insert({ id: Payment.PaymentId, at: new Date() });
}

user_received_badge

Fired when the paywall grants a badge — useful to pair the granted permission with the payment.

user_joined_group

Fired when the paywall adds the buyer to a group (ActionType 3 or 5).

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

Root

`User`

`Paywall`

`Payment`

Request headers

Use cases

Reacting to the event

user_received_badge

user_joined_group

Subscribing to webhooks

Webhooks (overview)

​Subscribe to this event

​When it fires

​When it does NOT fire

​Payload

​Payload fields

​Root

​User

​Paywall

​Payment

​Request headers

​Use cases

​Reacting to the event

​Related events

user_received_badge

user_joined_group

Subscribing to webhooks

Webhooks (overview)

Subscribe to this event

When it fires

When it does NOT fire

Payload

Payload fields

Root

`User`

`Paywall`

`Payment`

Request headers

Use cases

Reacting to the event

Related events