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: thePremium 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
- Cativa API Key — generated in the Console (Developers > API Keys). See Quick Start: API Key.
- Badge configured in the Console — create the
Premiumbadge (or whatever your product is called) and configure it as the access requirement on the group/course. See Badges as Permissions. - 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.
- A reliable buyer email — every gateway sends the email in the purchase payload. That’s the join key with the Cativa user.
Architecture
- 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.
user_received_badge webhook to fire a welcome email, update your CRM, or log an analytics event.
Implementation
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):Identify the user on Cativa by email
Two situations today:Case A — the buyer already has a Cativa account: you need to find their Case B — the buyer does not have a Cativa account yet: you need them to sign up first.
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.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).Assign the badge
Map the gateway Mental sketch of what it’ll look like: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.
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.
(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
Cancellation and chargeback
When the gateway cancels or charges back, you want to remove the badge to revoke access.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.
Common errors
Buyer doesn't have a Cativa account, paid and ended up without access
Buyer doesn't have a Cativa account, paid and ended up without access
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:Different email between gateway and Cativa for the same user
Different email between gateway and Cativa for the same user
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).
Gateway webhook fired twice — did the user get the badge twice?
Gateway webhook fired twice — did the user get the badge twice?
Badge assignment in Cativa is idempotent: applying the same badge twice produces the same final state. But for safety, store the gateway This also helps audit/reconcile later (e.g. financial report vs grants).
purchaseId in a local table and check before:Gateway offers "recurring subscription" — how do I handle monthly renewal?
Gateway offers "recurring subscription" — how do I handle monthly renewal?
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.Customer refunded in < 7 days but kept using the community
Customer refunded in < 7 days but kept using the community
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.
Multiple badges for the same product (course + bonus)
Multiple badges for the same product (course + bonus)
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.
