Webhooks

Os webhooks permitem que você receba notificações em tempo real quando eventos ocorrem na OlaClick. Em vez de fazer polling, a OlaClick envia um POST para seu endpoint sempre que algo relevante acontece.

Como funciona

1. Você registra uma URL via a API (veja Create Webhook na Referência da API REST)
2. Um evento ocorre na OlaClick (ex.: um pedido é criado)
3. A OlaClick envia um POST para sua URL com o payload do evento
4. Seu servidor responde com 2xx para confirmar o recebimento

Eventos disponíveis

Evento	Descrição
ORDER_CREATED	Um cliente finaliza um novo pedido
ORDER_UPDATED	O status do pedido muda (confirmado, em preparo, entregue, cancelado)
ORDER_DELETED	Um pedido é excluído do sistema

Formato de entrega

Cada entrega inclui os seguintes headers HTTP:

Header	Descrição
Content-Type	Sempre application/json
source	Sempre OlaClick
X-OlaClick-Signature	Assinatura HMAC-SHA256 do corpo da requisição, prefixada com sha256=

E um corpo JSON:

{
  "event_type": "ORDER_CREATED",
  "event_id": "unique-event-uuid",
  "merchant_id": "restaurant_042",
  "timestamp": "2026-06-20T15:30:00.000Z",
  "data": { ... }
}

Use event_id para idempotência — o mesmo evento pode ser entregue mais de uma vez devido a retentativas.

Verificando assinaturas de webhook

Toda entrega de webhook é assinada com o signing_secret do seu webhook usando HMAC-SHA256. Isso permite verificar que o payload foi enviado pela OlaClick e não foi adulterado.

A assinatura é enviada no header X-OlaClick-Signature no formato:

X-OlaClick-Signature: sha256=<hex-encoded-hmac>

Passos de verificação

1. Extraia o header X-OlaClick-Signature da requisição
2. Calcule o HMAC-SHA256 do corpo bruto da requisição usando seu signing_secret
3. Compare a assinatura calculada com a do header (use comparação resistente a timing attacks)

Exemplo (Node.js)

const crypto = require('crypto');

function verifySignature(body, secret, signatureHeader) {
  if (typeof signatureHeader !== 'string') return false;
  const expected = Buffer.from(
    'sha256=' + crypto.createHmac('sha256', secret).update(body).digest('hex'),
  );
  const received = Buffer.from(signatureHeader);
  // timingSafeEqual throws when lengths differ, so compare lengths first.
  return expected.length === received.length && crypto.timingSafeEqual(expected, received);
}

// No seu handler de webhook:
const rawBody = req.rawBody; // corpo bruto como string
const signature = req.headers['x-olaclick-signature'];
const isValid = verifySignature(rawBody, YOUR_SIGNING_SECRET, signature);

Exemplo (Python)

import hmac
import hashlib

def verify_signature(body: bytes, secret: str, signature_header: str) -> bool:
    if not signature_header:
        return False
    expected = 'sha256=' + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Notas importantes

• Sempre use o corpo bruto da requisição (não uma versão parseada/reserializada) para a verificação
• Use comparação resistente a timing attacks para prevenir timing attacks
• O signing_secret é retornado quando você cria ou atualiza um webhook via a API

Retentativas

Se seu endpoint não responder com um código de sucesso, a OlaClick tenta novamente até max_retry vezes com backoff exponencial (30s, 60s, 120s, ...).

Boas práticas

• Responda 200 imediatamente e processe em background
• Deduplique pelo event_id
• Verifique o header X-OlaClick-Signature para autenticar as entregas
• Use o corpo bruto da requisição (não o JSON reserializado) para a verificação de assinatura

Referência da API

O CRUD completo para gerenciar webhooks está na Referência da API REST, na seção Webhooks.