Webhook - Nova Venda

Este webhook é enviado sempre que uma nova venda é criada no sistema, independente do status de pagamento.

🔔 Quando é Disparado: Este webhook é disparado imediatamente após a criação de uma venda, quando o cliente finaliza o checkout e uma cobrança é gerada.

⚠️ Atenção: Neste momento, o pagamento ainda está pendente. Use o webhook de Atualização de Status para confirmar quando o pagamento for aprovado.

Estrutura do Payload

O payload deste webhook é idêntico ao webhook de Atualização de Status, mas sempre com payment_status como "pending".

Exemplo de Webhook

JSON Payload

{
  "transaction_token": "VCP1O8SB9GJ",
  "external_code": "EX001",
  "transaction_amount": 12000,
  "freight_amount": 2000,
  "automatic_discount": 1000,
  "products": [
    {
      "title": "Camiseta Azul",
      "code": "SKU123",
      "amount": 5000,
      "quantity": 2,
      "original_amount": 5000
    },
    {
      "title": "Seguro",
      "code": "SKU456",
      "amount": 1000,
      "quantity": 1,
      "original_amount": 1000
    }
  ],
  "customer": {
    "full_name": "Teste da Silva",
    "email": "teste.silva@example.com",
    "cellphone": "+5511999999999",
    "identification_number": "74600027043"
  },
  "customer_address": {
    "zip_code": "01310-922",
    "street": "Av. Paulista",
    "number": "1000",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "complement": "Conj. 101",
    "country": "BR"
  },
  "utms": {
    "src": "checkout_web",
    "utm_medium": "cpc",
    "utm_source": "google",
    "utm_campaign": "verao2025",
    "utm_content": "banner_home",
    "utm_term": "camiseta azul"
  },
  "payment_status": "pending",
  "payment_type": "pix",
  "date_created": "2024-10-07T14:20:30Z",
  "date_approved": null,
  "date_refunded": null
}

Casos de Uso

Analytics

Registre métricas de vendas iniciadas, mesmo que o pagamento ainda não tenha sido confirmado.

Notificações

Envie um e-mail para o cliente confirmando que o pedido foi criado e está aguardando pagamento.

Registro

Crie um registro do pedido no seu sistema para acompanhamento, mesmo antes da confirmação do pagamento.

Remarketing

Adicione o cliente em listas de remarketing para recuperar vendas não concluídas.

Exemplo de Implementação

PHP

<?php

// Recebe o payload
$payload = file_get_contents('php://input');
$data = json_decode($payload, true);

// Extrai informações
$transactionToken = $data['transaction_token'];
$externalCode = $data['external_code'];
$customer = $data['customer'];
$products = $data['products'];
$amount = $data['transaction_amount'];

// Verifica se já processou este webhook
if (webhookJaProcessado($transactionToken)) {
    http_response_code(200);
    echo json_encode(['status' => 'already_processed']);
    exit;
}

// Cria o pedido no sistema com status "aguardando pagamento"
$pedidoId = criarPedido([
    'external_code' => $externalCode,
    'transaction_token' => $transactionToken,
    'customer_name' => $customer['full_name'],
    'customer_email' => $customer['email'],
    'customer_phone' => $customer['cellphone'],
    'customer_cpf' => $customer['identification_number'],
    'amount' => $amount,
    'products' => $products,
    'status' => 'awaiting_payment',
    'payment_type' => $data['payment_type'],
    'created_at' => $data['date_created']
]);

// Envia e-mail para o cliente
enviarEmailPedidoCriado($customer['email'], [
    'pedido_id' => $pedidoId,
    'nome' => $customer['full_name'],
    'valor' => formatarValor($amount),
    'produtos' => $products
]);

// Registra evento no analytics
registrarEventoAnalytics('venda_iniciada', [
    'transaction_token' => $transactionToken,
    'valor' => $amount,
    'produtos' => count($products),
    'utm_source' => $data['utms']['utm_source'] ?? null,
    'utm_campaign' => $data['utms']['utm_campaign'] ?? null
]);

// Marca webhook como processado
marcarWebhookComoProcessado($transactionToken);

// Retorna sucesso
http_response_code(200);
echo json_encode([
    'status' => 'success',
    'pedido_id' => $pedidoId
]);

Fluxo Completo

Entenda o fluxo completo de webhooks de uma venda:

Nova Venda (Este Webhook)

Cliente finaliza o checkout → Venda criada com status pending

Pagamento Confirmado

Cliente paga via PIX → Webhook de Atualização enviado com status approved

Estorno (Opcional)

Se houver estorno ou chargeback → Webhook de Atualização com status refunded ou chargeback

💡 Dica: Não confie apenas neste webhook para liberar produtos ou serviços. Sempre aguarde o webhook de Atualização de Status com payment_status: "approved" antes de liberar o acesso.