SX
Webhooks

Webhooks

Receba notificacoes em tempo real sobre mudancas nos pagamentos. Configure uma URL para receber eventos automaticamente.

Configuracao

Para configurar webhooks, acesse o dashboard em Configuracoes > Webhooks e adicione a URL do seu endpoint.

Exemplo de URL:

https://seusite.com/api/webhooks/sellx

Eventos Disponiveis

order.createdPedido foi criado (aguardando pagamento)
order.paidPagamento foi confirmado
order.failedPagamento falhou ou foi recusado
order.refundedPagamento foi estornado

Payload do Webhook

JSON
// Payload do webhook - order.paid
{
  "event": "order.paid",
  "timestamp": "2024-01-15T14:30:00Z",
  "data": {
    "order": {
      "id": "uuid-do-pedido",
      "orderNumber": "ORD-123456",
      "status": "paid",
      "paymentMethod": "pix",
      "amount": 9900,
      "paidAt": "2024-01-15T14:30:00Z"
    },
    "customer": {
      "name": "Joao Silva",
      "email": "joao@email.com"
    },
    "product": {
      "name": "Curso Online"
    }
  }
}

Verificacao de Assinatura

Importante

Sempre verifique a assinatura do webhook antes de processar o evento. Isso garante que a requisicao veio realmente do SellX Checkout.

Cada requisicao inclui os headers X-Webhook-Signature (assinatura HMAC-SHA256) e X-Webhook-Event (tipo do evento).

JavaScript
// Verificar assinatura do webhook
import crypto from 'crypto';

function verifyWebhookSignature(payload, signature, secret) {
  // Remove o prefixo 'sha256=' se presente
  const sig = signature.replace('sha256=', '');

  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(sig),
    Buffer.from(expectedSignature)
  );
}

// No seu endpoint (Express.js)
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const event = req.headers['x-webhook-event'];

  if (!verifyWebhookSignature(req.body, signature, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Processar evento
  const { data } = req.body;

  switch (event) {
    case 'order.paid':
      // Liberar acesso ao produto
      console.log('Pedido pago:', data.order.orderNumber);
      break;
    case 'order.failed':
      // Notificar cliente
      break;
  }

  res.json({ received: true });
});

Boas Praticas

Responda rapidamente

Retorne uma resposta 200 em ate 5 segundos. Processe eventos pesados de forma assincrona.

Seja idempotente

O mesmo evento pode ser enviado mais de uma vez. Use o orderId para evitar processamento duplicado.

Trate falhas

Em caso de falha, reenviaremos o webhook ate 5 vezes com backoff exponencial.