OmniTicketz API Documentation

Webhooks

Receba notificações em tempo real quando eventos acontecem no OmniTicketz. Configure URLs de callback para receber dados automaticamente.

Como Funciona

Quando um evento acontece (ex: pedido pago), o OmniTicketz envia um POST HTTP para a URL configurada no seu painel. O payload contém todos os dados relevantes do evento.

Configuração via Painel

Acesse Integrações > Webhooks no painel admin para configurar suas URLs de callback, selecionar eventos e obter seu secret para validação HMAC.

Eventos Disponíveis

Parâmetro	Tipo	Padrão	Descrição
`pedido.pago`	event	—	Disparado quando um pedido é marcado como pago (online ou PDV)

Formato do Payload

O webhook envia um POST com o seguinte formato JSON:

200Payload do evento pedido.pago

{
  "evento": "pedido.pago",
  "timestamp": "2026-02-06T14:30:00.000Z",
  "tenant_id": "uuid-do-tenant",
  "dados": {
    "pedido_id": "uuid-do-pedido",
    "numero_pedido": "20260206-0001",
    "status": "pago",
    "total": 280.00,
    "origem": "online",
    "pago_em": "2026-02-06T14:30:00.000Z",
    "cliente": {
      "nome": "Maria Silva",
      "email": "maria@email.com",
      "cpf": "12345678900"
    },
    "itens": [
      {
        "ingresso_nome": "Pacote Day Use",
        "lote_nome": "Adulto COM Almoço",
        "quantidade": 2,
        "preco_unitario": 140.00
      }
    ]
  }
}

Headers Enviados

Parâmetro	Tipo	Padrão	Descrição
`Content-Type`	header	—	application/json
`X-Webhook-Signature`	header	—	HMAC-SHA256 do body para validação de autenticidade
`X-Webhook-Event`	header	—	Nome do evento (ex: pedido.pago)
`X-Webhook-Timestamp`	header	—	Timestamp ISO 8601 do envio

Validação HMAC-SHA256

Para garantir que o webhook foi enviado pelo OmniTicketz, valide a assinatura usando o secret do webhook:

const crypto = require("crypto");

function validateWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// No seu endpoint:
app.post("/webhook", (req, res) => {
  const signature = req.headers["x-webhook-signature"];
  const isValid = validateWebhook(
    JSON.stringify(req.body),
    signature,
    "seu_webhook_secret"
  );

  if (!isValid) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  // Processar evento...
  res.status(200).json({ received: true });
});

Boas Práticas

Recomendações

Sempre valide a assinatura HMAC antes de processar o evento
Retorne 200 OK rapidamente (em menos de 5 segundos)
Processe eventos de forma assíncrona se necessário
Implemente idempotência usando o pedido_id como chave
O OmniTicketz fará até 3 tentativas de reenvio em caso de falha

QR Code Check-in

API Playground