Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cativa.digital/llms.txt

Use this file to discover all available pages before exploring further.

You sell a course or digital product on an external gateway (Hotmart, Kiwify, Eduzz, Stripe Checkout) and want the purchase to automatically unlock access to a group, course or space inside your Cativa community. This guide walks through the recommended architecture, what’s available today and what’s coming soon.

Scenario

A customer buys “Premium Course” on Hotmart. Within seconds they get access to the “Premium Students” group and to the course inside your Cativa community. The bridge between both sides is the badge-as-permission concept: the Premium badge is configured in the Console as the access requirement on that group and course. Once the user gets the badge, access shows up automatically. When the badge is removed, access is gone.

Prerequisites

  1. Cativa API Key — generated in the Console (Developers > API Keys). See Quick Start: API Key.
  2. Badge configured in the Console — create the Premium badge (or whatever your product is called) and configure it as the access requirement on the group/course. See Badges as Permissions.
  3. Purchase webhook from your gateway — Hotmart, Kiwify, Eduzz and Stripe fire a webhook to your server’s endpoint when a purchase is confirmed. Do not point the gateway webhook directly at Cativa — you need a proxy server that receives, validates and translates the event.
  4. A reliable buyer email — every gateway sends the email in the purchase payload. That’s the join key with the Cativa user.

Architecture

   Customer buys on Hotmart


   Hotmart webhook ──► Your server (proxy) ──► Cativa API (assign badge)


                                         Cativa user_received_badge webhook


                                              Email/CRM/Analytics
You’re the broker between gateway and Cativa. That gives you control to:
  • Validate the gateway webhook (each one has its own signature — check the gateway docs).
  • Handle idempotency (Hotmart can fire the same webhook twice).
  • Log the gateway purchase ID for audit/reconciliation.
  • Decide the right badge based on which product was purchased.
You can optionally subscribe to the Cativa user_received_badge webhook to fire a welcome email, update your CRM, or log an analytics event.

Implementation

1

Receive the gateway webhook

Each gateway has its own webhook format and its own signing mechanism. Configure the webhook in the gateway dashboard pointing to an endpoint on your server (e.g. https://myapp.com/webhooks/hotmart).Cativa does not document the gateway webhook formats — refer to the official docs:Receiver skeleton (Express, Hotmart example):
import express from 'express';

const app = express();

app.post(
  '/webhooks/hotmart',
  express.json(),
  async (req, res) => {
    // 1. Verify the gateway signature here (per gateway docs)

    const event = req.body;
    // Hotmart uses event types like "PURCHASE_APPROVED", "PURCHASE_CANCELED", etc.

    if (event.event === 'PURCHASE_APPROVED') {
      await handlePurchase({
        email: event.data.buyer.email,
        productId: event.data.product.id,
        purchaseId: event.data.purchase.transaction
      });
    }

    if (event.event === 'PURCHASE_CANCELED' ||
        event.event === 'PURCHASE_REFUNDED' ||
        event.event === 'PURCHASE_CHARGEBACK') {
      await handleCancellation({
        email: event.data.buyer.email,
        productId: event.data.product.id,
        purchaseId: event.data.purchase.transaction
      });
    }

    // Reply 2xx fast — process the rest in the background if you can.
    res.status(200).send('ok');
  }
);
Always verify the gateway webhook signature before trusting the data. Without it, anyone who finds your URL could grant arbitrary badges.
2

Identify the user on Cativa by email

Two situations today:Case A — the buyer already has a Cativa account: you need to find their User.Id.
The public endpoint for partners to look up an arbitrary user by email is coming soon. Today, that lookup uses an admin endpoint that’s not available to partner API Keys.Recommended workaround: keep a local email → cativa_user_id table populated by Cativa’s user_created webhook. Every time someone joins the community, you save the row. When the purchase arrives, you look up locally with no API call.
async function resolveCativaUserId(email) {
  const row = await db.userMap.findOne({ email });
  return row?.cativaUserId ?? null;
}
Case B — the buyer does not have a Cativa account yet: you need them to sign up first.
User creation directly via partner API Key is coming soon. Workaround today: send an email with the tenant’s sign-up link plus a note that the badge will be granted once they join. When they sign up, the user_created webhook lands on your server and you complete the flow (see step 4).
async function inviteBuyer({ email, productId, purchaseId }) {
  // Save the grant intent to complete it when user_created arrives
  await db.pendingGrants.insert({
    email,
    productId,
    purchaseId,
    createdAt: new Date()
  });

  // Send email with the tenant's sign-up link
  await mailer.send({
    to: email,
    subject: 'Your access to Premium Course',
    text: `Sign up at https://{customerName}.cativa.digital/signup?email=${encodeURIComponent(email)} to unlock your access.`
  });
}
3

Assign the badge

Map the gateway productId to the Cativa badgeId configured in the Console.
Badge assignment via partner API Key is coming soon. Today, assigning/removing badges happens in the Console (manually or via import) or through internal platform flows. When the public endpoint is available, this page will be updated with the full cURL. To unblock your case in the meantime, open a ticket at dev@cativa.digital.
Mental sketch of what it’ll look like:
const PRODUCT_TO_BADGE = {
  'hotmart_product_123': 'badge_uuid_premium',
  'hotmart_product_456': 'badge_uuid_mentoring_2026'
};

async function handlePurchase({ email, productId, purchaseId }) {
  const badgeId = PRODUCT_TO_BADGE[productId];
  if (!badgeId) {
    console.warn(`No badge mapped for product ${productId}`);
    return;
  }

  const cativaUserId = await resolveCativaUserId(email);
  if (!cativaUserId) {
    await inviteBuyer({ email, productId, purchaseId });
    return;
  }

  // When the endpoint is available:
  const res = await fetch(
    `https://apis.cativalab.digital/social/v1/.../badges/${badgeId}/users/${cativaUserId}`,
    {
      method: 'POST',
      headers: { Authorization: `Bearer ${process.env.CATIVA_API_KEY}` }
    }
  );
  if (!res.ok) throw new Error(`Badge assign failed: ${res.status}`);

  await db.purchases.insert({
    purchaseId,
    cativaUserId,
    badgeId,
    grantedAt: new Date()
  });
}
Cativa guarantees that assigning the same badge twice is idempotent (see Badges as Permissions) — so retries caused by timeouts or gateway redelivery do not double-grant.
4

(Optional) React to the user_received_badge webhook

Cativa fires user_received_badge every time a badge is assigned (regardless of whether it came from the API, Console, or another flow). Subscribe a listener to it if you want to:
  • Send a welcome email with a link to the community
  • Update the contact status in your CRM
  • Track conversion in analytics
See Subscribing and verifying webhooks for the listener-subscription steps and HMAC verification. The event payload is documented at user_received_badge.Receiver skeleton:
import express from 'express';
import crypto from 'crypto';

const SECRET = process.env.CATIVA_WEBHOOK_SECRET; // whsec_...

app.post(
  '/webhooks/cativa',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    // HMAC verification — see /webhooks/subscribing-and-verifying
    const sigHeader = req.header('X-Cativa-Signature') ?? '';
    const parts = Object.fromEntries(
      sigHeader.split(',').map(p => p.split('='))
    );
    const ts = Number(parts.t);
    const sig = parts.v1;
    if (Math.abs(Date.now() / 1000 - ts) > 300) return res.status(400).end();
    const expected = crypto
      .createHmac('sha256', SECRET)
      .update(`${ts}.${req.body.toString('utf8')}`)
      .digest('hex');
    if (!crypto.timingSafeEqual(
      Buffer.from(expected, 'hex'),
      Buffer.from(sig, 'hex')
    )) return res.status(401).end();

    const event = JSON.parse(req.body.toString('utf8'));

    if (event.BadgeName === 'Premium') {
      await sendWelcomeEmail(event.User.Email, event.User.FirstName);
      await analytics.track('Purchase Activated', {
        email: event.User.Email,
        badge: event.BadgeName
      });
    }

    res.status(200).send('ok');
  }
);

Cancellation and chargeback

When the gateway cancels or charges back, you want to remove the badge to revoke access.
async function handleCancellation({ email, productId, purchaseId }) {
  const badgeId = PRODUCT_TO_BADGE[productId];
  if (!badgeId) return;

  const cativaUserId = await resolveCativaUserId(email);
  if (!cativaUserId) return;

  // When the endpoint is available:
  await fetch(
    `https://apis.cativalab.digital/social/v1/.../badges/${badgeId}/users/${cativaUserId}`,
    {
      method: 'DELETE',
      headers: { Authorization: `Bearer ${process.env.CATIVA_API_KEY}` }
    }
  );

  await db.purchases.update({ purchaseId }, { revokedAt: new Date() });
}
Badge removal via partner API Key is on the same waitlist as assignment. Same workaround: today it’s done in the Console; the public endpoint is shipping soon.
Removing the badge is enough — group, course and space access tied to the badge disappears immediately.

Common errors

Most common case. The customer bought on Hotmart before joining your community.Fix: step 2 above covers it — register the intent in pendingGrants and send the invite. Subscribe the user_created webhook and, when sign-up happens, complete the assignment:
// user_created listener
if (event.event === 'user_created') {
  const pending = await db.pendingGrants.findAll({ email: event.User.Email });
  for (const grant of pending) {
    await handlePurchase({
      email: event.User.Email,
      productId: grant.productId,
      purchaseId: grant.purchaseId
    });
    await db.pendingGrants.delete({ id: grant.id });
  }
}
Happens when the customer pays with a personal email and joins the community with a corporate one. No automatic fix.Fix: offer an “I already bought, but I’m logged in with a different email” page in your app where the customer enters the purchase email. You validate the purchase ID locally and assign the badge to the logged-in user (not to the purchase email).
Badge assignment in Cativa is idempotent: applying the same badge twice produces the same final state. But for safety, store the gateway purchaseId in a local table and check before:
if (await db.purchases.exists({ purchaseId })) {
  return; // already processed
}
This also helps audit/reconcile later (e.g. financial report vs grants).
Each gateway fires a webhook when the renewal is charged successfully (e.g. Hotmart SUBSCRIPTION_CHARGE_SUCCESS). Treat it as an idempotent handlePurchase — re-apply the badge (no effect if already there). If the renewal fails (e.g. card declined), treat it as handleCancellation.
You need to react to chargeback fast — the gateway webhook arrives, you remove the badge, access to the resources tied to it disappears. Don’t rely on a nightly batch job for this.
Map a product to multiple badges when needed. Example: product Premium Course unlocks both Premium (course access) and Mentoring-2026 (mentoring group access). Make two assignments inside handlePurchase.

Next steps

Cativa webhooks

Subscribe listeners for user_created (cover the “bought before signing up” case) and user_received_badge (trigger post-access actions).

Sync members from your CRM

If you also run a CRM, combine this flow with tag sync to have a single hub of permissions.