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), ConversaLabs 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
Payment and card sending are separate states
In the conversation's Commerce panel, the title describes the recorded commerce event and Card sending describes only the send attempt for that card. Payment confirmed together with Not attempted does not mean payment is pending: the financial confirmation is recorded, but this Commerce card has no recorded send attempt yet. Other payment messages may already be in the conversation.
Use View card to open the linked message when available, or Open conversation to review the history. Send confirmation or Resend confirmation opens a dialog before sending; you can cancel. This action does not create a charge or change the financial confirmation. Resending an existing card requires your explicit confirmation. Without a linked conversation, the server looks for an existing conversation with the contact; this panel does not open a new one.
A card recorded in the conversation does not prove customer receipt: check the message and channel status too. Failures, refused sends and unconfirmed responses are not presented as success. Messages and boletos sent before settlement remain in the history; their presence does not make a confirmed payment pending. Do not use a receipt image to replace the financial status recorded by the gateway or an authorized operator.
- 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.
Who appears as the recovery card's author
When an active AI assistant or bot sends the recovery card, the message is recorded with that bot as its author. It must be active in the conversation's inbox, in the same account, and the event used for recovery must belong to the same contact as the conversation.
When a human agent sends the card, the message is recorded with that agent as its author.
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: ConversaLabs 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.
A recorded message or a card visible in the conversation does not confirm delivery through the customer's channel. Before saying the customer received it, check the message's delivery status and the channel connection.
Troubleshooting
-
A resend received no confirmed response: the server may already have accepted the card. The panel blocks another attempt and offers Check recorded outcome, which only reads records. If no outcome can be verified yet, review the conversation; this check does not resend the card. The protection remains on closing and reopening confirmation. With browser session storage available, it also survives reloading in the same tab; if storage is denied, it lasts while the panel is mounted. This is not delivery proof or protection across browser tabs.
-
The charge status changed: an old confirmation event is not resent when the current native charge is refunded, canceled or in another incompatible state. Review Payments.
-
PIX/boleto disappeared after payment: old instruments remain in history, but are no longer offered for settled, refunded, canceled or archived charges. A partial refund does not create a new debt. Genuinely open installments of a plan retain their payment actions.
-
A confirmation cannot be sent outside the WhatsApp window: use an approved confirmation template without a configured payment button. A collection template is not reused for a settled charge. Check that its approved content and static buttons also match the confirmation's purpose.
-
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.
-
The bot doesn't send the recovery card: check that it is active in the conversation's inbox, in the same account, and that the event belongs to the same contact as the conversation.
-
The card appears, but the customer didn't receive it: check the message's delivery status and the channel connection before confirming receipt to the customer.