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

# Eventos

> Referência dos eventos que a Velan dispara para as integrações configuradas.

Ao criar ou atualizar uma integração, você define a lista de `events` que a ativam. Cada evento corresponde a uma mudança de estado de um pedido ou a uma ação do comprador.

## Eventos disponíveis

| Valor             | Label               | Descrição                                                                                 |
| ----------------- | ------------------- | ----------------------------------------------------------------------------------------- |
| `order.paid`      | Pedido Pago         | Disparado quando o pagamento é confirmado.                                                |
| `order.created`   | Pedido Criado       | Disparado assim que o pedido é gerado (antes do pagamento).                               |
| `order.refunded`  | Pedido Estornado    | Disparado quando um reembolso é processado.                                               |
| `order.expired`   | Pedido Expirado     | Disparado quando o prazo de pagamento vence.                                              |
| `order.failed`    | Pedido Falhou       | Disparado quando a tentativa de pagamento é recusada.                                     |
| `order.abandoned` | Carrinho Abandonado | Disparado quando um pedido permanece sem pagamento após o checkout (carrinho abandonado). |
| `lead.created`    | Lead Criado         | Disparado quando um novo lead é registrado via checkout.                                  |

<Tip>
  Para a maioria das integrações de vendas, assine ao menos `order.paid` e `order.refunded`. Use `order.created` para rastrear intenções de compra em ferramentas de analytics.
</Tip>

***

## Suporte por tipo de integração

Nem todos os tipos processam todos os eventos. A tabela abaixo indica os eventos reconhecidos por cada tipo:

| Tipo                        | `order.paid` | `order.created` | `order.refunded` | `order.expired` | `order.failed` | `order.abandoned` | `lead.created` |
| --------------------------- | :----------: | :-------------: | :--------------: | :-------------: | :------------: | :---------------: | :------------: |
| webhook                     |       ✓      |        ✓        |         ✓        |        ✓        |        ✓       |         ✓         |        ✓       |
| roigenius                   |       ✓      |        ✓        |         ✓        |        ✓        |        ✓       |         ✓         |        ✓       |
| active\_campaign            |       ✓      |        ✓        |         ✓        |        ✓        |        ✓       |         ✓         |        ✓       |
| make                        |       ✓      |        ✓        |         ✓        |        ✓        |        ✓       |         ✓         |        —       |
| zapier                      |       ✓      |        ✓        |         ✓        |        ✓        |        ✓       |         ✓         |        —       |
| google\_analytics           |       ✓      |        ✓        |         ✓        |        ✓        |        ✓       |         ✓         |        —       |
| utmify                      |       ✓      |        ✓        |         ✓        |        ✓        |        ✓       |         ✓         |        —       |
| hotzapp                     |       ✓      |        ✓        |         ✓        |        ✓        |        ✓       |         ✓         |        —       |
| meta\_pixel                 |       ✓      |        ✓        |         —        |        —        |        —       |         ✓         |        ✓       |
| cademi                      |       ✓      |        —        |         ✓        |        —        |        —       |         —         |        —       |
| themembers                  |       ✓      |        —        |         ✓        |        —        |        —       |         —         |        —       |
| curseduca                   |       ✓      |        —        |         ✓        |        —        |        —       |         —         |        —       |
| circle                      |       ✓      |        —        |         ✓        |        —        |        —       |         —         |        —       |
| memberkit                   |       ✓      |        —        |         ✓        |        —        |        —       |         —         |        —       |
| leadlovers                  |       ✓      |        —        |         ✓        |        —        |        —       |         —         |        —       |
| rdstation                   |       ✓      |        —        |         ✓        |        —        |        —       |         —         |        —       |
| mailchimp                   |       ✓      |        —        |         ✓        |        —        |        —       |         —         |        —       |
| voxuy                       |       ✓      |        —        |         ✓        |        —        |        —       |         —         |        —       |
| spedy                       |       ✓      |        —        |         ✓        |        —        |        —       |         —         |        —       |
| bling                       |       ✓      |        —        |         ✓        |        —        |        —       |         —         |        —       |
| notazz / enotas / plugnotas |       ✓      |        —        |         ✓        |        —        |        —       |         —         |        —       |

<Note>
  Ao configurar uma integração, só é possível assinar os eventos que aquele tipo realmente despacha (a lista acima). Eventos não suportados são rejeitados na criação/edição.
</Note>

<Note>
  Os tipos `webhook` e `roigenius` encaminham o payload completo para **qualquer** evento (incluindo `lead.created`). Os tipos `make` e `zapier` encaminham apenas eventos de pedido (`order.*`).
</Note>

<Note>
  O tipo `webhook` também pode assinar o evento `checkout.viewed` (visualização do checkout, opt-in) — exclusivo de webhooks, com envelope próprio sem dados pessoais. Veja [CHECKOUT\_VIEWED](/integrations/webhook/checkout-viewed).
</Note>

***

## Payload do evento

O payload segue o envelope no formato Hotmart **2.0.0**. Um exemplo de `order.paid` (entregue como `PURCHASE_APPROVED`):

```json theme={null}
{
  "id": "6f6a2b3c-9d1e-4a5b-8c7d-0e1f2a3b4c5d",
  "order_id": 123,
  "creation_date": 1736524800000,
  "event": "PURCHASE_APPROVED",
  "version": "2.0.0",
  "data": {
    "purchase": {
      "transaction": "ABC123DEF456",
      "status": "APPROVED",
      "order_date": 1736524000000,
      "approved_date": 1736524800000,
      "refund_date": null,
      "full_price": {
        "value": 297.00,
        "currency_value": "BRL"
      },
      "price": {
        "value": 197.00,
        "currency_value": "BRL"
      },
      "payment": {
        "type": "CREDIT_CARD",
        "installments_number": 12
      },
      "offer": {
        "code": "OFF-001",
        "name": "Oferta Black Friday"
      },
      "order_bump": {
        "is_order_bump": false,
        "parent_purchase_transaction": null
      },
      "tracking": {
        "source": "google",
        "utm_source": "google",
        "utm_medium": "cpc",
        "utm_campaign": "black-friday",
        "utm_content": null,
        "utm_term": null,
        "src": null,
        "sck": null,
        "fbclid": "IwAR..."
      }
    },
    "product": {
      "id": 1,
      "name": "Curso de Marketing Digital"
    },
    "buyer": {
      "id": 456,
      "name": "João Silva",
      "first_name": "João",
      "last_name": "Silva",
      "email": "joao@exemplo.com",
      "checkout_phone": "+5511999990000",
      "document": "123.456.789-00",
      "document_type": "CPF",
      "client_ip": "177.0.0.1",
      "client_user_agent": "Mozilla/5.0 ..."
    },
    "order_bumps": []
  }
}
```

<Tip>
  O campo `purchase.transaction` é o identificador único do pedido e pode ser usado como chave de idempotência na sua integração.
</Tip>

### Valor assinado × valor entregue

O evento que você **assina** na configuração (`order.paid`, `order.refunded`, …) não é o mesmo texto que chega no campo **`event`** do payload — este usa a nomenclatura Hotmart. Filtre sempre pelo valor da coluna `event` abaixo:

| Evento assinado   | Campo `event` entregue     | `purchase.status`                              |
| ----------------- | -------------------------- | ---------------------------------------------- |
| `order.paid`      | `PURCHASE_APPROVED`        | `APPROVED`                                     |
| `order.created`   | `PURCHASE_WAITING_PAYMENT` | `WAITING_PAYMENT` (PIX) / `PENDING` (cartão)   |
| `order.refunded`  | `PURCHASE_REFUNDED`        | `REFUNDED`                                     |
| `order.expired`   | `PURCHASE_EXPIRED`         | `EXPIRED`                                      |
| `order.failed`    | `PURCHASE_CANCELLED`       | `CANCELLED`                                    |
| `order.abandoned` | `PURCHASE_CART_ABANDONED`  | `PENDING`                                      |
| `lead.created`    | `LEAD_CREATED`             | — (envelope diferente, sem `purchase`/`buyer`) |

<Note>
  O evento `lead.created` usa um envelope próprio (sem `purchase` e `buyer`). Veja [Lead Criado](/integrations/webhook/lead-created) para o formato.
</Note>

***

## Rastreamento (`tracking`)

Todos os eventos `order.*` incluem `data.purchase.tracking` (e os eventos `lead.created` incluem `data.lead.tracking`). O objeto contém **todos os parâmetros de URL** capturados no checkout, exatamente como vieram, acrescidos das chaves de UTM padronizadas — que estarão sempre presentes (com valor `null` quando ausentes):

| Campo                                                                 | Descrição                                                                                                         |
| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `source`                                                              | Origem resolvida: `utm_source` ou, na falta dele, `src`.                                                          |
| `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term` | Parâmetros UTM padrão.                                                                                            |
| `src`, `sck`                                                          | Códigos de rastreamento de afiliado/origem.                                                                       |
| *(outros)*                                                            | Qualquer parâmetro extra presente na URL do checkout (ex.: `fbclid`, `gclid`, `xcod`) é repassado no mesmo nível. |

<Note>
  As chaves de UTM acima são garantidas no objeto (mesmo que `null`). Parâmetros adicionais aparecem apenas quando presentes na URL — não assuma um conjunto fixo de chaves.
</Note>