Overview
The e-commerce lifecycle connects external platforms — Kiwify, Hotmart, Nuvemshop and Shopify — so that sales events arrive inside your support. When something happens on the external platform (abandoned cart, PIX/boleto generated, purchase approved, declined or refunded), Conversa Labs receives the webhook, normalizes the event, and shows a card in the customer's conversation, with payment data when available.
With this, you recover sales without switching tools: the team sees the purchase stage right in the conversation and can trigger automatic Follow-ups to win back anyone who didn't complete.
Prerequisites
- The Catalog & Commerce module enabled and permission to configure commerce sources.
- Access to the external platform (Kiwify, Hotmart, Nuvemshop or Shopify) to set up the webhook.
- For automatic recovery: the Follow-ups module configured with event-triggered sequences.
Step by step
- In the Catalog & Commerce area, create a commerce source for the desired platform.
- Copy the complete webhook URL generated for that source. It includes both the account and the source; do not remove either segment. Also configure the verification secret. On Kiwify, automatic registration can generate and save the token; on Hotmart, enter the application's Hottok.
- Paste the URL into the external platform's panel (or use automatic registration when available, for example on Kiwify and Nuvemshop).
- Make a test sale (or a test cart) to confirm the event arrives.
- See the event card appear in the customer's conversation, with items, amounts and the payment link/data depending on the stage.
- Set up event-triggered Follow-ups (for example, "abandoned cart") to recover the sale automatically.
Settings & options
- Commerce source: one per platform, with its own webhook URL and verification secret.
- Automatic webhook registration: available on some platforms (e.g. Kiwify and Nuvemshop); on the others, setup is manual in the platform's own panel.
- Event card: shows the purchase stage and, when the platform exposes it, PIX/boleto data and the checkout link.
- Commerce variables: data from the latest event is available for use in Follow-up messages (payment link, amount, PIX/boleto code, etc.).
Choose which events to receive
When you edit the source under Catalog → Sync sources → edit the source, the Events section lists the events that platform sends and lets you map each one to a lifecycle stage — or set it to Off (ignore) to drop it entirely.
Every enabled event flows through the rest of the platform: automations, flows, webhooks, Follow-up and the CRM. The mapping is what decides which stage it becomes.
A prominent Abandoned cart recovery switch turns the platform's abandoned-cart event on and off — it
is what drives the recovery cadence in Follow-up (the commerce.cart_abandoned trigger).
Available for:
| Source | Events you map |
|---|---|
| Hotmart | purchase, cart, subscription and members-area events |
| Kiwify | its 10 real triggers: compra_aprovada, pix_gerado, boleto_gerado, compra_recusada, compra_reembolsada, chargeback, carrinho_abandonado, subscription_renewed, subscription_late, subscription_canceled |
| Nuvemshop | the order's payment_status values: paid, authorized, pending, refunded, partially_refunded, abandoned — the Nuvemshop webhook carries only the ID, so the stage comes from the order's payment status |
| Generic sources | the documented event names from your system. You explicitly set the event field, ID, buyer/product/item paths and the canonical stage for each event; nothing is inferred from a platform name |
Managed sources with no verified sale-lifecycle contract, such as Mercado Livre and OLX, do not show an event selector. Sources powered by the generic connector — including a custom Shopify/API setup — show the signed generic webhook configuration and only receive the events you explicitly map.
The defaults are sensible: you only change the mapping if you want a different stage, or if you want to ignore an event.
Use cases
- Abandoned cart: triggers a Follow-up sequence reminding the customer to finish.
- Pending PIX/boleto: resends the payment code and follows up until confirmed.
- Approved purchase: confirms with the customer and unlocks the next support step.
- Refund/decline: alerts the team to handle the case right in the conversation.
Tips, limits & best practices
- What each platform exposes varies: some send the PIX code and the boleto line in the event (full recovery inside the conversation); others only provide the checkout link — in those cases, the card shows the link for the customer to complete.
- Amounts and formats differ per platform: Conversa Labs normalizes each event; you don't need to worry about conversion — the card already displays the correct amount.
- Verification secret: keep it configured so only legitimate events from the platform are accepted. Hotmart, Kiwify, Nuvemshop and generic webhooks are rejected when no secret is configured. A generic sender must also provide the documented timestamped signature and one stable delivery ID per event.
- Combine with Follow-ups to automate recovery instead of relying on manual action.
Troubleshooting
- The event doesn't appear: check that the complete webhook URL was pasted correctly into the platform and that the verification secret is configured and matches.
- I don't see PIX/boleto on the card: not every platform exposes that data; when it doesn't, the card carries the checkout link.
- Duplicate events: generic deliveries with the same delivery ID are acknowledged only once. If something looks off, confirm that the sender reuses that ID on retries and that only one webhook is configured for the same source.