Visão Geral dos Eventos

Eventos são o resultado do processamento de webhooks recebidos das plataformas integradas. Este documento apresenta a estrutura geral e as famílias de eventos disponíveis.

Estrutura do Evento

Todo evento segue o mesmo envelope, com variações apenas no campo payload:

{
  "id": "0192abcd-1234-5678-9abc-def012345679",
  "installation_id": "0192abcd-1234-5678-9abc-def012345678",
  "integration_driver_slug": "hotmart",
  "name": "order.paid",
  "created_at": 1705319100,
  "payload": {
    "customer": { ... },
    "order": { ... }
  },
  "superseded": false,
  "superseded_by": null,
  "webhook_dispatched_at": 1705319105
}

Campos do Envelope

Campo	Tipo	Descrição
id	string	ID único do evento (UUID)
installation_id	string	ID da instalação que originou o evento
integration_driver_slug	string	Slug do Driver que gerou o evento (ex: hotmart, shopify)
name	string	Nome do evento no formato {domínio}.{ação} (ex: order.paid)
created_at	integer	Timestamp (Unix, em segundos) de criação do registro do evento
payload	object	Payload normalizado do evento (varia por família)
superseded	boolean	Indica se o evento foi marcado como “fora de ordem” por superseding
superseded_by	object | null	Referência do evento que supersede este (quando superseded = true)
webhook_dispatched_at	integer | null	Timestamp (Unix, em segundos) do envio para a webhook_url (quando houver envio)

Famílias de Eventos

Família	Descrição	Eventos
Order	Pedidos e transações	order.*
Checkout	Checkouts abandonados	checkout.*
Subscription	Ciclo de vida de assinaturas	subscription.*
Subscription Transaction	Transações de assinaturas (cobranças)	subscription.transaction.*
Shipping	Rastreamento de entregas	shipping.*
Fiscal Invoice	Notas fiscais	fiscal_invoice.*
Reverse Logistic	Logística reversa	reverse_logistic.*

Nomenclatura dos Eventos

Os eventos seguem o padrão: {domínio}.{ação} ou {domínio}.{subdomínio}.{ação}

Exemplos:

• order.paid - Pedido pago
• order.waiting_payment.pix - Aguardando pagamento via PIX
• subscription.transaction.paid - Transação de assinatura paga
• shipping.delivered - Entrega realizada
• reverse_logistic.return.approved - Devolução aprovada

Detecção de Sequência Incorreta (Superseding)

O campo superseded indica que a plataforma detectou uma inconsistência na sequência de eventos. Isso ocorre quando recebemos um evento que deveria ter sido processado antes de outro evento já recebido para o mesmo pedido.

Exemplo: Se recebermos order.paid antes de order.waiting_payment para a mesma order, o sistema marca o order.waiting_payment como:

• superseded: true
• superseded_by: { event_id, event_name } (referenciando o order.paid)

Isso indica que o fluxo de eventos chegou fora da ordem esperada. O evento superseded ainda é válido e deve ser processado, mas você deve estar ciente de que o estado já foi alterado por um evento posterior.

Campos Comuns no Payload

A estrutura do payload varia por família, mas mantém consistência nos objetos principais:

Customer

{
  "customer": {
    "id": "123456",
    "name": "João Silva",
    "email": "[email protected]",
    "document": "12345678900",
    "phone_numbers": [
      {
        "formatted_phone": "+5511999999999",
        "type": null,
        "raw_number": "999999999",
        "area_code": "11",
        "international_dialing_code": "55"
      }
    ],
    "address": {
      "street": "Rua Principal",
      "number": "123",
      "complement": "Apto 45",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR",
      "postal_code": "01000-000"
    }
  }
}

Payment Method

Consulte a documentação completa dos Métodos de Pagamento para detalhes sobre cada tipo suportado (CreditCard, Pix, Boleto, etc).

Valores Monetários

Todos os valores são representados em centavos (inteiro):

{
  "payment": {
    "currency": "BRL",
    "total": 29990,
    "discount_value": 500,
    "shipping_value": 1500,
    "total_products_value": 27990
  }
}

Timestamps

Todos os timestamps são em segundos Unix (não milissegundos):

{
  "order": {
    "created_at": 1705319000,
    "paid_at": 1705319100,
    "updated_at": 1705319100
  }
}

Próximos Passos

• Order - Eventos de pedidos
• Checkout - Checkouts abandonados
• Subscription - Assinaturas
• Subscription Transaction - Transações de assinaturas
• Shipping - Entregas
• Fiscal Invoice - Notas fiscais
• Reverse Logistic - Logística reversa