Skip to main content

Webhooks

Webhooks permitem que a Obra Play notifique seu sistema automaticamente quando eventos importantes acontecem na plataforma — sem que você precise ficar consultando a API periodicamente (polling).

Quando um evento ocorre, a Obra Play faz uma requisição POST para a URL que você configurou, enviando os dados do evento em JSON.

Como configurar um webhook​

Cadastre a URL do seu endpoint via API:

POST /api/hooks/
Authorization: Token seu_token_aqui
Content-Type: application/json

{
  "url": "https://sua-plataforma.com/webhooks/obraplay",
  "event": "quotation.published"
}

Para listar seus webhooks cadastrados:

GET /api/hooks/
Authorization: Token seu_token_aqui
Testando localmente

Durante o desenvolvimento, use o ngrok para expor seu servidor local e receber webhooks:

ngrok http 3000
# Copie a URL gerada e use como endpoint do webhook

Estrutura do payload​

Todos os webhooks seguem a mesma estrutura de envelope:

{
  "event": "quotation.published",
  "timestamp": "2026-04-16T14:32:00Z",
  "data": {
    // objeto do recurso que gerou o evento
  }
}
CampoTipoDescrição
eventstringIdentificador do evento (ex: quotation.published)
timestampstringData e hora do evento em UTC (ISO 8601)
dataobjectDados completos do recurso relacionado

Eventos disponíveis​

EventoDescrição
company.membership_createdUm novo membro foi adicionado a uma empresa
company.membership_updatedA associação de um membro em uma empresa foi atualizada
company.membership_deletedA associação de um membro em uma empresa foi removida
company.createdUma nova empresa foi criada na plataforma
company.updatedOs dados de uma empresa foram atualizados
company.deletedUma empresa foi removida da plataforma
company.configuredA configuração inicial de uma empresa foi concluída
company.address_confirmedO endereço de uma empresa foi confirmado
company.verifiedUma empresa foi verificada e aprovada na plataforma
quotation.createdUma nova cotação foi criada
quotation.updatedUma cotação foi atualizada
quotation.deletedUma cotação foi removida
quotation_answer.createdUma nova resposta a uma cotação foi criada
quotation_answer.updatedUma resposta a uma cotação foi atualizada
quotation_answer.finalizedUma resposta a uma cotação foi finalizada
quotation_answer.autofilledUma resposta a uma cotação foi preenchida automaticamente
quotation_answer.renegotiateUma renegociação de resposta a cotação foi iniciada
quotation_answer.deletedUma resposta a uma cotação foi removida
quotation_answer_message.createdUma nova mensagem foi enviada em uma resposta de cotação
quotation_answer_message.updatedUma mensagem em uma resposta de cotação foi atualizada
quotation_answer_message.deletedUma mensagem em uma resposta de cotação foi removida
order.updatedUma ordem de compra foi atualizado
order.processedUma ordem de compra foi processado e confirmado pelo fornecedor
order.refusedUma ordem de compra foi recusado pelo fornecedor
order.canceledUma ordem de compra foi cancelado
order.finalizedUma ordem de compra foi finalizado e a entrega confirmada
order_review.createdUma nova avaliação de pedido foi criada
order_review.updatedUma avaliação de pedido foi atualizada
order_review.deletedUma avaliação de pedido foi removida
user.createdUm novo usuário foi criado na plataforma
user.updatedOs dados de um usuário foram atualizados

Respondendo ao webhook​

Seu endpoint deve retornar um status 2xx (preferencialmente 200 OK) em até 5 segundos para confirmar o recebimento.

Se a Obra Play não receber uma resposta 2xx, a entrega será considerada falha e o evento será reenviado com backoff exponencial.

Processe de forma assíncrona

Não execute lógica pesada durante o tratamento do webhook. Retorne 200 imediatamente e processe o evento em background (fila, worker, etc.) para evitar timeout.

Verificando a autenticidade​

Todos os webhooks enviados pela Obra Play incluem um header de assinatura para garantir que a requisição é legítima:

X-ObraPlay-Signature: sha256=abc123...

Valide a assinatura calculando o HMAC-SHA256 do corpo da requisição com o seu webhook secret (disponível no painel de configurações da integração) e comparando com o valor do header.

Exemplo em Python:

import hmac
import hashlib

def verify_signature(payload_body: bytes, secret: str, signature_header: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature_header)

Exemplo em Node.js:

const crypto = require('crypto');

function verifySignature(payloadBody, secret, signatureHeader) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payloadBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(`sha256=${expected}`),
    Buffer.from(signatureHeader)
  );
}