Skip to main content
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. Modal de configuração do Webhook
CampoDescrição
Ativar para todos os produtosQuando ativo, o webhook recebe eventos de todos os produtos da empresa. Quando inativo, você seleciona os produtos manualmente.
TítuloNome interno para identificar a integração no painel.
URLEndpoint HTTP que receberá os eventos via POST.
AutenticaçãoBearer Token ou Basic Auth — adicionados ao header Authorization de cada requisição.

​
Campos de configuração

CampoTipoObrigatórioDescrição
urlstring✓URL que receberá os eventos via POST. Pode incluir um token diretamente na query string (ex: ?token=...)
auth_tokenstring—Token enviado no header Authorization: Bearer {token}.
auth_usernamestring—Usuário para autenticação Authorization: Basic.
auth_passwordstring—Senha para autenticação Basic (use junto com auth_username).
secretstring—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"
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
      },
      "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"
    }
  }
}
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.

​
Mapeamento de eventos

O campo event no payload usa nomenclatura compatível com o padrão Hotmart:
EventType (config)Payload event
order.paidPURCHASE_APPROVED
order.refundedPURCHASE_REFUNDED
order.createdPURCHASE_WAITING_PAYMENT
order.expiredPURCHASE_EXPIRED
order.failedPURCHASE_CANCELLED
order.abandonedPURCHASE_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:
Eventopurchase.statusapproved_daterefund_date
order.createdWAITING_PAYMENT ou PENDINGnullnull
order.paidAPPROVEDtimestampnull
order.refundedREFUNDEDtimestamptimestamp
order.failedCANCELLEDnullnull
order.expiredEXPIREDnullnull
order.abandonedPENDINGnullnull
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 internopurchase.status
pendingPENDING
awaiting_pixWAITING_PAYMENT
paidAPPROVED
failedCANCELLED
expiredEXPIRED
refundedREFUNDED

​
Mapeamento de método de pagamento

Método internopayment.type
pixPIX
credit_cardCREDIT_CARD
billetBILLET
card_pixCREDIT_CARD
two_cardsTWO_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.createdLEAD_CREATED

​
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