> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rovax.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Hotmart

> Hotmart events consumed by Timely.ai — purchases, cancellations, and subscriptions for billing and access automations

**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

<Steps>
  <Step title="Access the Hotmart dashboard">
    Go to **Tools → Webhooks** in your Hotmart account (producer or co-producer).
  </Step>

  <Step title="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.
  </Step>

  <Step title="Select events">
    Select `PURCHASE_COMPLETE`, `PURCHASE_CANCELED`, `PURCHASE_REFUNDED`, `SUBSCRIPTION_CANCELLATION`, and others as needed.
  </Step>

  <Step title="Save and test">
    Use Hotmart's **Test** button to send a sample payload to your endpoint.
  </Step>
</Steps>

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

```typescript Node.js theme={null}
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);
});
```

<Warning>
  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.
</Warning>

## Event: PURCHASE\_COMPLETE

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

```json theme={null}
{
  "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).

```json theme={null}
{
  "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.

```json theme={null}
{
  "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).

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Welcome message via WhatsApp" icon="whatsapp">
    On receiving `PURCHASE_COMPLETE`, send an automatic message via the Timely agent using the buyer's `phone`.
  </Card>

  <Card title="Revoke access" icon="user-slash">
    On receiving `SUBSCRIPTION_CANCELLATION`, remove the contact from groups or mark them as inactive in Timely's CRM.
  </Card>

  <Card title="Bank slip recovery" icon="file-invoice">
    On receiving `PURCHASE_EXPIRED`, start a recovery flow with a message and a new payment link.
  </Card>

  <Card title="CRM update" icon="address-book">
    Sync buyer data as a contact in Timely using the Contacts API.
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Contacts — API Reference" icon="address-book" href="/en/api-reference/contacts/referencia">
    Create and update contacts programmatically when receiving Hotmart events.
  </Card>

  <Card title="Webhooks — API Reference" icon="bell" href="/en/api-reference/webhooks/referencia">
    Configure endpoints to receive events from your Timely workspace.
  </Card>
</CardGroup>