Skip to main content
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:
  1. Direct webhook: Hotmart sends events to a Timely endpoint (or your own server), which triggers automations in the workspace.
  2. Native integration: configure the webhook URL generated by your Timely agent directly in the Hotmart dashboard.

​
Configure the webhook URL in Hotmart

1

Access the Hotmart dashboard

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

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.
3

Select events

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

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

EventWhen it occurs
PURCHASE_COMPLETEPurchase approved
PURCHASE_CANCELEDPurchase canceled
PURCHASE_REFUNDEDRefund approved
PURCHASE_CHARGEBACKChargeback filed
PURCHASE_PROTESTDispute opened
PURCHASE_DELAYEDDelayed payment (bank slip)
PURCHASE_EXPIREDBank slip expired without payment
SUBSCRIPTION_CANCELLATIONSubscription canceled
SWITCH_PLANBuyer changed plans

​
Key payload fields

FieldTypeDescription
idstringUnique Hotmart event ID (HP-*)
eventstringEvent type
creation_datenumberTimestamp in milliseconds
data.product.idnumberProduct ID in Hotmart
data.purchase.transactionstringUnique transaction code
data.purchase.statusstringPurchase status
data.buyer.emailstringBuyer’s email
data.buyer.phonestringPhone number (international format)
data.subscription.subscriber_codestringUnique 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.