Webhook - Documentation

Webhooks permitem que você receba os dados de cada evento diretamente no seu servidor via POST HTTP, sem precisar fazer polling na API.

Integrando com IA?

Copie o arquivo llms.txt e cole no seu assistente de IA (Claude, ChatGPT, Cursor…). Ele contém o contrato completo do webhook — payload, campos, enums e schema de banco de dados — para que a IA gere a integração por você.

Configurando no painel

Card da integração Webhook no painel da Velan

Na tela de integrações, clique em INTEGRAR no card de Webhooks para abrir o modal de configuração.

Campo	Descrição
Ativar para todos os produtos	Quando ativo, o webhook recebe eventos de todos os produtos da empresa. Quando inativo, você seleciona os produtos manualmente.
Título	Nome interno para identificar a integração no painel.
URL	Endpoint HTTP que receberá os eventos via `POST`.
Autenticação	Bearer Token ou Basic Auth — adicionados ao header `Authorization` de cada requisição.
Order bumps em eventos separados	Opcional (padrão: desativado). A partir da aprovação, envia a venda separada: parte principal + um evento por order bump (pedido próprio, mesmo código do painel). Veja Vendas com order bump e upsell.

Campos de configuração

Campo	Tipo	Obrigatório	Descrição
`url`	string	✓	URL que receberá os eventos via POST. Pode incluir um token diretamente na query string (ex: `?token=...`)
`auth_token`	string	—	Token enviado no header `Authorization: Bearer {token}`.
`auth_username`	string	—	Usuário para autenticação `Authorization: Basic`.
`auth_password`	string	—	Senha para autenticação Basic (use junto com `auth_username`).
`secret`	string	—	Chave para assinatura HMAC-SHA256 do body. Compatível com qualquer `auth_type` — pode ser usado em conjunto.

A forma mais simples de autenticar é incluir um token diretamente na URL — sem configuração extra:

https://api.example.com.br/hook?token=e80ca832-6cb9-40df-b1ee-8a47ce408c16

Validando que a requisição veio da Velan

Qualquer pessoa que descubra a URL do seu webhook pode tentar enviar dados falsos para ela. O campo secret resolve isso: você define uma senha secreta que só você e a Velan conhecem. A cada requisição, a Velan usa essa senha para gerar um código único a partir do conteúdo enviado e inclui esse código no header X-Velan-Signature. No seu servidor, você refaz o mesmo cálculo e compara — se os códigos batem, a requisição é legítima.

X-Velan-Signature: sha256={codigo_gerado}

Se você já usa autenticação por token na URL (?token=...), o secret é opcional. Use os dois juntos para uma camada extra de segurança.

Como verificar no seu servidor:

BODY='{"event":"PURCHASE_APPROVED","version":"2.0.0"}'
SECRET="meu-segredo-hmac"

SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

echo "X-Velan-Signature: sha256=$SIGNATURE"

import hashlib
import hmac

def verify_signature(body: bytes, secret: str, header: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    received = header.removeprefix("sha256=")
    return hmac.compare_digest(expected, received)

const crypto = require("crypto");

function verifySignature(body, secret, header) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  const received = header.replace("sha256=", "");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(received)
  );
}

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "strings"
)

func verifySignature(body []byte, secret, header string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(body)
    expected := hex.EncodeToString(mac.Sum(nil))
    received := strings.TrimPrefix(header, "sha256=")
    return hmac.Equal([]byte(expected), []byte(received))
}

Use sempre uma comparação segura contra timing attacks (hmac.compare_digest, crypto.timingSafeEqual, hmac.Equal) — nunca ==.

Payload de eventos de pedido

Todos os eventos relacionados a pedidos (order.*) entregam o mesmo envelope:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "order_id": 123,
  "creation_date": 1736524800000,
  "event": "PURCHASE_APPROVED",
  "version": "2.0.0",
  "data": {
    "purchase": {
      "transaction": "abc123-uuid-do-pedido",
      "status": "APPROVED",
      "order_date": 1736524700000,
      "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": 3
      },
      "fees": {
        "value": 13.45,
        "currency_value": "BRL"
      },
      "net_amount": {
        "value": 183.55,
        "currency_value": "BRL"
      },
      "gateway_transaction_id": "172691451499",
      "offer": {
        "code": "oferta-abc",
        "name": "Oferta Principal"
      },
      "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
      }
    },
    "product": {
      "id": 1,
      "name": "Curso de Marketing Digital"
    },
    "buyer": {
      "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"
    },
    "order_bumps": []
  }
}

O objeto purchase.tracking traz todos os parâmetros de URL capturados no checkout, com as chaves de UTM sempre presentes (null quando ausentes). Veja Eventos → Rastreamento.

Vendas com order bump e upsell

Uma venda pode reunir vários produtos — o principal, order bumps marcados no checkout e um upsell aceito depois do pagamento. Os eventos ficam assim:

Item da venda	Evento gerado
Produto principal + order bumps	Um único evento `order.` — `purchase.price` traz o total da compra* (principal + bumps) e `data.order_bumps` lista cada bump
Upsell aceito	Outro evento `order.paid`, com `purchase.transaction` próprio (o upsell é um pedido separado, cobrado no cartão salvo)

O array data.order_bumps vem vazio ([]) quando a venda não tem bumps. Com bumps, cada item traz o produto e a oferta adicionais:

"order_bumps": [
  {
    "product_id": 42,
    "product_name": "Planilha de Investimentos",
    "offer_code": "bump1234",
    "offer_name": "Planilha - 50% OFF",
    "price": 47.00,
    "amount": 47.00
  }
]

Campo	Descrição
`product_id` / `product_name`	Produto liberado pelo bump
`offer_code` / `offer_name`	Oferta do bump como exibida no checkout
`price`	Preço base do bump
`amount`	Valor cobrado do bump (com juros do parcelamento, quando houver)

Não some purchase.price com os valores de data.order_bumps: o total da compra já está em purchase.price. O array existe para você saber quais produtos compõem a venda (ex.: liberar acesso por produto).

Opcional: um evento por order bump

Se o seu sistema consome vendas por produto, ative “Order bumps em eventos separados” na configuração do webhook. Com a opção ativa, cada order bump da venda vira um pedido próprio na Velan (o mesmo que aparece no painel do produtor), e o webhook recebe um evento por pedido:

Campo	Valor no evento do bump
`purchase.transaction`	UUID real do pedido do bump — o mesmo exibido no painel
`purchase.price` / `full_price`	Valores da linha do bump (não o total)
`purchase.offer` / `data.product`	Oferta e produto do bump
`purchase.order_bump.is_order_bump`	`true`
`purchase.order_bump.parent_purchase_transaction`	UUID do pedido principal

Nesse modo, o evento principal (purchase.transaction do pedido principal) traz apenas o valor da parte principal da compra — cada bump carrega o próprio valor no próprio evento. Somando principal + bumps você chega ao total da venda, sem risco de contar valores em dobro.

Os eventos por bump são emitidos a partir da aprovação do pagamento (order.paid) e no estorno (order.refunded, total ou por item). Eventos anteriores ao pagamento (order.created, order.abandoned, order.expired, order.failed) continuam sendo um único evento da compra inteira, com os bumps listados em data.order_bumps.

Com a opção desativada (padrão), nada muda: o evento de pedido representa a compra inteira, com o total em purchase.price e os bumps em data.order_bumps, e purchase.order_bump.is_order_bump é sempre false.

Mapeamento de eventos

O campo event no payload usa nomenclatura compatível com o padrão Hotmart:

EventType (config)	Payload `event`
`order.paid`	`PURCHASE_APPROVED`
`order.refunded`	`PURCHASE_REFUNDED`
`order.created`	`PURCHASE_WAITING_PAYMENT`
`order.expired`	`PURCHASE_EXPIRED`
`order.failed`	`PURCHASE_CANCELLED`
`order.abandoned`	`PURCHASE_CART_ABANDONED`

Variação de campos por evento

Todos os eventos order.* entregam o mesmo envelope. O que muda entre eles são os valores de três campos:

Evento	`purchase.status`	`approved_date`	`refund_date`
`order.created`	`WAITING_PAYMENT` ou `PENDING`	`null`	`null`
`order.paid`	`APPROVED`	timestamp	`null`
`order.refunded`	`REFUNDED`	timestamp	timestamp
`order.failed`	`CANCELLED`	`null`	`null`
`order.expired`	`EXPIRED`	`null`	`null`
`order.abandoned`	`PENDING`	`null`	`null`

approved_date só é preenchido após confirmação do pagamento. refund_date só é preenchido quando o reembolso é processado. Nos demais eventos, ambos são null.

Mapeamento de status

O campo purchase.status segue a nomenclatura Hotmart:

Status interno	`purchase.status`
`pending`	`PENDING`
`awaiting_pix`	`WAITING_PAYMENT`
`paid`	`APPROVED`
`failed`	`CANCELLED`
`expired`	`EXPIRED`
`refunded`	`REFUNDED`

Mapeamento de método de pagamento

Método interno	`payment.type`
`pix`	`PIX`
`credit_card`	`CREDIT_CARD`
`billet`	`BILLET`
`card_pix`	`CREDIT_CARD`
`two_cards`	`TWO_CREDIT_CARDS`

Payload de lead criado

O evento lead.created usa um envelope diferente — não contém purchase nem buyer. O campo event é LEAD_CREATED:

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "lead_id": 456,
  "creation_date": 1736524800000,
  "event": "LEAD_CREATED",
  "version": "2.0.0",
  "data": {
    "lead": {
      "code": "uuid-do-lead",
      "name": "Maria Souza",
      "email": "maria@exemplo.com",
      "phone": "+5521988880000",
      "status": "new",
      "ip": "177.0.0.1",
      "country": "BR",
      "city": "São Paulo",
      "region": "SP",
      "tracking": {
        "source": "google",
        "utm_source": "google",
        "utm_medium": "cpc",
        "utm_campaign": "black-friday",
        "utm_content": null,
        "utm_term": null,
        "src": null,
        "sck": null
      }
    },
    "product": {
      "id": 1,
      "name": "Curso de Marketing Digital",
      "type": "digital",
      "offer_code": "oferta-abc",
      "price": 197.00
    }
  }
}

EventType (config)	Payload `event`
`lead.created`	`LEAD_CREATED`

Evento de visualização de checkout (`checkout.viewed`)

Evento opt-in exclusivo de webhooks: disparado quando um visitante abre a página do checkout, antes de preencher qualquer dado. Usa um envelope próprio, sem purchase, buyer ou lead — nenhum dado pessoal. Deduplicado por visitante + oferta (janela de 6 horas). Veja o payload completo em CHECKOUT_VIEWED.

EventType (config)	Payload `event`
`checkout.viewed`	`CHECKOUT_VIEWED`

Boas práticas

Responda com HTTP 2xx o mais rápido possível. Se precisar processar, enfileire a tarefa e responda imediatamente.
A Velan faz retry automático em caso de falha. Após 10 falhas consecutivas, a integração é desativada pelo circuit breaker.
Use o campo purchase.transaction (UUID do pedido) como chave de idempotência para evitar processamento duplicado.

Referência para LLMs

Para sistemas de IA ou automações que precisam entender o contrato completo deste webhook (schema detalhado de todos os campos, enums, nullability, persistência recomendada e ciclo de vida dos eventos), consulte o arquivo de referência estruturado: /integrations/webhook/llms.txt

Integrando com IA?

​Configurando no painel

​Campos de configuração

​Validando que a requisição veio da Velan

​Payload de eventos de pedido

​Vendas com order bump e upsell

​Opcional: um evento por order bump

​Mapeamento de eventos

​Variação de campos por evento

​Mapeamento de status

​Mapeamento de método de pagamento

​Payload de lead criado

​Evento de visualização de checkout (checkout.viewed)

​Boas práticas

​Referência para LLMs

Configurando no painel

Campos de configuração

Validando que a requisição veio da Velan

Payload de eventos de pedido

Vendas com order bump e upsell

Opcional: um evento por order bump

Mapeamento de eventos

Variação de campos por evento

Mapeamento de status

Mapeamento de método de pagamento

Payload de lead criado

Evento de visualização de checkout (`checkout.viewed`)

Boas práticas

Referência para LLMs