Webhooks: documentação do CheckoutOS

Os webhooks permitem receber notificações em tempo real quando eventos ocorrem no CheckoutOS. Em vez de consultar a API repetidamente, os webhooks enviam dados ao seu servidor conforme os eventos acontecem.

Eventos disponíveis

Eventos de webhook

upsell.accepted — O cliente aceitou uma oferta de venda adicional
upsell.declined — O cliente recusou uma oferta de venda adicional
bundle.purchased — Um kit foi comprado
experiment.concluded — O teste A/B atingiu significância
order.edited — O cliente editou o pedido
order.cancelled — O cliente cancelou o pedido
subscription.created — A oferta de assinatura gerou uma conversão

Criação de webhooks

Acessar os webhooks

Acesse CheckoutOS → Settings → Webhooks.

Adicionar endpoint

Clique em "Add Webhook Endpoint".

Inserir URL

Insira a URL HTTPS que receberá os eventos.

Selecionar eventos

Escolha quais eventos deseja receber.

Salvar

Salve e anote o segredo de assinatura.

Criar webhook via API

curl -X POST "https://api.chargezen.com/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourserver.com/webhooks/checkoutos",
    "events": ["upsell.accepted", "bundle.purchased"],
    "enabled": true
  }'

# Response
{
  "id": "wh_123",
  "url": "https://yourserver.com/webhooks/checkoutos",
  "events": ["upsell.accepted", "bundle.purchased"],
  "signing_secret": "whsec_abc123...",
  "enabled": true
}

Payload do webhook

upsell.accepted

Evento de oferta adicional aceita

{
  "id": "evt_123456",
  "type": "upsell.accepted",
  "created_at": "2025-01-16T14:30:00Z",
  "data": {
    "upsell_id": "upsell_abc",
    "upsell_name": "Premium Add-On",
    "order_id": "order_789",
    "shopify_order_id": "5678901234",
    "customer_id": "cust_456",
    "product": {
      "id": "prod_xyz",
      "title": "Premium Widget",
      "variant_id": "var_123",
      "price": 29.99
    },
    "discount": {
      "type": "percentage",
      "value": 15,
      "amount": 4.50
    },
    "final_price": 25.49
  }
}

bundle.purchased

Evento de kit comprado

{
  "id": "evt_234567",
  "type": "bundle.purchased",
  "created_at": "2025-01-16T15:00:00Z",
  "data": {
    "bundle_id": "bundle_def",
    "bundle_name": "Skincare Starter Kit",
    "bundle_type": "fixed",
    "order_id": "order_890",
    "products": [
      { "id": "prod_a", "title": "Cleanser", "quantity": 1 },
      { "id": "prod_b", "title": "Toner", "quantity": 1 },
      { "id": "prod_c", "title": "Moisturizer", "quantity": 1 }
    ],
    "original_price": 89.97,
    "bundle_price": 71.98,
    "savings": 17.99
  }
}

order.edited

Evento de pedido editado

{
  "id": "evt_345678",
  "type": "order.edited",
  "created_at": "2025-01-16T15:30:00Z",
  "data": {
    "order_id": "order_901",
    "shopify_order_id": "6789012345",
    "edit_type": "add_items",
    "changes": {
      "items_added": [
        { "product_id": "prod_new", "quantity": 1, "price": 19.99 }
      ],
      "items_removed": [],
      "quantity_changes": []
    },
    "amount_changed": 19.99,
    "new_total": 109.98
  }
}

Verificação de webhooks

Todos os webhooks incluem um cabeçalho de assinatura para verificação:

Verificação em Node.js

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expectedSignature}`)
  );
}

// Express middleware
app.post('/webhooks/checkoutos', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-checkoutos-signature'];

  if (!verifyWebhook(req.body, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  // Handle event...

  res.status(200).send('OK');
});

Verificação em Python

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(
        f'sha256={expected}',
        signature
    )

# Flask example
@app.route('/webhooks/checkoutos', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-CheckoutOS-Signature')

    if not verify_webhook(request.data, signature, WEBHOOK_SECRET):
        return 'Invalid signature', 401

    event = request.get_json()
    # Handle event...

    return 'OK', 200

Sempre verifique

Sempre verifique as assinaturas dos webhooks antes do processamento. Isso impede que invasores enviem eventos falsos ao seu endpoint.

Política de novas tentativas

Entregas de webhook que falham são repetidas com intervalos que aumentam exponencialmente:

Cronograma de novas tentativas

{
  "retry_policy": {
    "max_attempts": 5,
    "schedule": [
      { "attempt": 1, "delay": "immediately" },
      { "attempt": 2, "delay": "5 minutes" },
      { "attempt": 3, "delay": "30 minutes" },
      { "attempt": 4, "delay": "2 hours" },
      { "attempt": 5, "delay": "24 hours" }
    ],
    "success_codes": [200, 201, 202, 204],
    "timeout": "30 seconds"
  }
}

Teste de webhooks

Teste o endpoint do webhook antes de colocá-lo em produção:

Enviar evento de teste

curl -X POST "https://api.chargezen.com/v1/webhooks/wh_123/test" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "upsell.accepted"
  }'

Logs de webhooks

Veja o histórico de entregas dos webhooks no painel ou pela API:

Obter logs de webhooks

curl -X GET "https://api.chargezen.com/v1/webhooks/wh_123/logs" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": [
    {
      "id": "log_123",
      "event_id": "evt_456",
      "event_type": "upsell.accepted",
      "status": "delivered",
      "response_code": 200,
      "duration_ms": 245,
      "created_at": "2025-01-16T14:30:00Z"
    }
  ]
}

Boas práticas

Dicas para webhooks

Responda rapidamente — Retorne 200 em até 30 segundos
Processe de forma assíncrona — Coloque os eventos em fila para processamento em segundo plano
Trate duplicatas — Os eventos podem ser entregues várias vezes
Verifique as assinaturas — Sempre valide antes de processar
Monitore falhas — Configure alertas para entregas que falharem

Tópicos relacionados

Autenticação

Gestão de chaves de API

Saiba mais

Endpoints da API

Referência completa dos endpoints

Saiba mais