Hotmart - Timely.ai

Hotmart is a digital product sales platform widely used in Brazil. Timely.ai lets you integrate Hotmart events with your AI agents — for example, automatically granting access to a group, sending a welcome message via WhatsApp, or updating a contact in the CRM every time a purchase is approved. The integration works in two models:

Direct webhook: Hotmart sends events to a Timely endpoint (or your own server), which triggers automations in the workspace.
Native integration: configure the webhook URL generated by your Timely agent directly in the Hotmart dashboard.

Configure the webhook URL in Hotmart

Access the Hotmart dashboard

Go to Tools → Webhooks in your Hotmart account (producer or co-producer).

Add a new webhook

Click Add webhook and enter the URL. To send events to a Timely agent, use the endpoint generated under Settings → Channels → Incoming Webhook in your workspace.

Select events

Select PURCHASE_COMPLETE, PURCHASE_CANCELED, PURCHASE_REFUNDED, SUBSCRIPTION_CANCELLATION, and others as needed.

Save and test

Use Hotmart’s Test button to send a sample payload to your endpoint.

Hotmart signature validation

Hotmart sends the X-Hotmart-Webhook-Token header with a fixed token you configure in the dashboard. This is not HMAC — it is a direct token comparison. For that reason, make sure to use HTTPS and keep the token secret.

Node.js

const HOTMART_TOKEN = process.env.HOTMART_WEBHOOK_TOKEN!;

app.post("/webhook/hotmart", (req, res) => {
  const token = req.headers["x-hotmart-webhook-token"];
  if (token !== HOTMART_TOKEN) {
    return res.status(401).json({ error: "Invalid token" });
  }
  // process the event...
  res.sendStatus(200);
});

Because Hotmart does not use HMAC, any server with the token can forge a request. Use the token only over HTTPS, never over HTTP, and never expose the token in logs.

Event: PURCHASE_COMPLETE

Triggered when a purchase is approved (credit card, cleared bank slip, confirmed PIX).

{
  "id": "HP-1234567890",
  "creation_date": 1713456789000,
  "event": "PURCHASE_COMPLETE",
  "version": "2.0.0",
  "data": {
    "product": {
      "id": 123456,
      "name": "Curso de Automação com IA",
      "ucode": "PRODUTO_UCODE"
    },
    "purchase": {
      "approved_date": 1713456789000,
      "full_price": {
        "value": 297.0,
        "currency_value": "BRL"
      },
      "order_date": 1713456700000,
      "status": "APPROVED",
      "transaction": "HP-1234567890",
      "payment": {
        "type": "CREDIT_CARD",
        "installments_number": 3
      },
      "offer": {
        "code": "OFERTA_BASICA",
        "payment_mode": "PAYMENT"
      }
    },
    "buyer": {
      "name": "Maria Oliveira",
      "email": "maria@exemplo.com.br",
      "phone": "+5511988887777",
      "document": "***.***.***-**"
    },
    "subscription": null,
    "commissions": []
  }
}

Event: PURCHASE_CANCELED

Triggered when a purchase is canceled before compensation (expired bank slip, card definitively declined).

{
  "id": "HP-1234567891",
  "creation_date": 1713543200000,
  "event": "PURCHASE_CANCELED",
  "version": "2.0.0",
  "data": {
    "product": {
      "id": 123456,
      "name": "Curso de Automação com IA",
      "ucode": "PRODUTO_UCODE"
    },
    "purchase": {
      "status": "CANCELED",
      "transaction": "HP-1234567891",
      "cancellation_date": 1713543200000,
      "payment": {
        "type": "BOLETO",
        "installments_number": 1
      }
    },
    "buyer": {
      "name": "Carlos Mendes",
      "email": "carlos@exemplo.com.br",
      "phone": "+5511977776666",
      "document": "***.***.***-**"
    }
  }
}

Event: PURCHASE_REFUNDED

Triggered when a refund is approved after the purchase was already completed.

{
  "id": "HP-1234567892",
  "creation_date": 1713629800000,
  "event": "PURCHASE_REFUNDED",
  "version": "2.0.0",
  "data": {
    "product": {
      "id": 123456,
      "name": "Curso de Automação com IA",
      "ucode": "PRODUTO_UCODE"
    },
    "purchase": {
      "status": "REFUNDED",
      "transaction": "HP-1234567890",
      "full_price": {
        "value": 297.0,
        "currency_value": "BRL"
      }
    },
    "buyer": {
      "name": "Maria Oliveira",
      "email": "maria@exemplo.com.br",
      "phone": "+5511988887777"
    }
  }
}

Event: SUBSCRIPTION_CANCELLATION

Triggered when a recurring subscription is canceled (by the buyer or the producer).

{
  "id": "HP-1234567893",
  "creation_date": 1713716200000,
  "event": "SUBSCRIPTION_CANCELLATION",
  "version": "2.0.0",
  "data": {
    "product": {
      "id": 123456,
      "name": "Mentoria Mensal IA",
      "ucode": "PRODUTO_UCODE"
    },
    "purchase": {
      "status": "CANCELLED_BY_CUSTOMER",
      "transaction": "HP-1234567893",
      "subscription_anticipation_purchase": false
    },
    "subscription": {
      "subscriber_code": "SUB-ABC12345",
      "status": "CANCELLED",
      "plan": {
        "name": "Plano Mensal",
        "recurrency_period": 30
      },
      "date_next_charge": null
    },
    "buyer": {
      "name": "Pedro Ramos",
      "email": "pedro@exemplo.com.br",
      "phone": "+5511966665555"
    }
  }
}

Other available events

Event	When it occurs
`PURCHASE_COMPLETE`	Purchase approved
`PURCHASE_CANCELED`	Purchase canceled
`PURCHASE_REFUNDED`	Refund approved
`PURCHASE_CHARGEBACK`	Chargeback filed
`PURCHASE_PROTEST`	Dispute opened
`PURCHASE_DELAYED`	Delayed payment (bank slip)
`PURCHASE_EXPIRED`	Bank slip expired without payment
`SUBSCRIPTION_CANCELLATION`	Subscription canceled
`SWITCH_PLAN`	Buyer changed plans

Key payload fields

Field	Type	Description
`id`	string	Unique Hotmart event ID (`HP-*`)
`event`	string	Event type
`creation_date`	number	Timestamp in milliseconds
`data.product.id`	number	Product ID in Hotmart
`data.purchase.transaction`	string	Unique transaction code
`data.purchase.status`	string	Purchase status
`data.buyer.email`	string	Buyer’s email
`data.buyer.phone`	string	Phone number (international format)
`data.subscription.subscriber_code`	string	Unique subscriber code

Common automations with Hotmart

Welcome message via WhatsApp

On receiving PURCHASE_COMPLETE, send an automatic message via the Timely agent using the buyer’s phone.

Revoke access

On receiving SUBSCRIPTION_CANCELLATION, remove the contact from groups or mark them as inactive in Timely’s CRM.

Bank slip recovery

On receiving PURCHASE_EXPIRED, start a recovery flow with a message and a new payment link.

CRM update

Sync buyer data as a contact in Timely using the Contacts API.

Next steps

Contacts — API Reference

Create and update contacts programmatically when receiving Hotmart events.

Webhooks — API Reference

Configure endpoints to receive events from your Timely workspace.

​Configure the webhook URL in Hotmart

​Hotmart signature validation

​Event: PURCHASE_COMPLETE

​Event: PURCHASE_CANCELED

​Event: PURCHASE_REFUNDED

​Event: SUBSCRIPTION_CANCELLATION

​Other available events

​Key payload fields

​Common automations with Hotmart

Welcome message via WhatsApp

Revoke access

Bank slip recovery

CRM update

​Next steps

Contacts — API Reference

Webhooks — API Reference

Configure the webhook URL in Hotmart

Hotmart signature validation

Event: PURCHASE_COMPLETE

Event: PURCHASE_CANCELED

Event: PURCHASE_REFUNDED

Event: SUBSCRIPTION_CANCELLATION

Other available events

Key payload fields

Common automations with Hotmart

Next steps