API

Webhooks

Receber notificações de eventos em tempo real via webhooks.

Webhooks

Receba notificações em tempo real quando eventos ocorrem no OctaBuild. Webhooks permitem que sua aplicação reaja automaticamente a mudanças em terrenos, empreendimentos, unidades e registros financeiros.

Webhooks estão em desenvolvimento. Esta documentação descreve a interface planejada.

Como Funciona

OctaBuild                        Sua Aplicação
    │                                  │
    │  1. Evento ocorre                │
    │  (ex: terreno criado)            │
    │                                  │
    │  2. POST com payload ──────────► │
    │                                  │
    │  ◄──────── 3. Responde 200 OK    │
    │                                  │

Eventos Disponíveis

Terrenos

EventoDescrição
land_plot.createdTerreno cadastrado
land_plot.updatedTerreno atualizado
land_plot.status_changedStatus do terreno alterado
land_plot.score_updatedScore IA recalculado
land_plot.deletedTerreno removido

Empreendimentos

EventoDescrição
development.createdEmpreendimento criado
development.updatedEmpreendimento atualizado
development.phase_changedFase do empreendimento alterada
development.archivedEmpreendimento arquivado

Unidades

EventoDescrição
unit.createdUnidade cadastrada
unit.updatedUnidade atualizada
unit.status_changedStatus da unidade alterado
unit.bulk_createdUnidades criadas em lote

Clientes

EventoDescrição
client.createdCliente cadastrado
client.updatedCliente atualizado
client.deactivatedCliente desativado

Financeiro

EventoDescrição
financial.payable_createdConta a pagar criada
financial.payable_paidConta a pagar quitada
financial.receivable_createdConta a receber criada
financial.receivable_confirmedRecebimento confirmado
financial.overdueConta vencida sem pagamento

Formato do Payload

Todos os webhooks enviam um payload JSON via POST:

{
  "id": "wh_evt_550e8400e29b41d4a716446655440000",
  "event": "land_plot.status_changed",
  "created_at": "2026-02-25T10:30:00Z",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Terreno Alphaville",
    "status": "due_diligence",
    "previous_status": "negociacao"
  }
}

Headers

Cada requisição webhook inclui os seguintes headers:

HeaderDescrição
Content-Typeapplication/json
X-OctaBuild-EventNome do evento (ex: land_plot.created)
X-OctaBuild-SignatureAssinatura HMAC-SHA256 do payload
X-OctaBuild-TimestampTimestamp Unix da requisição
X-OctaBuild-DeliveryID único da entrega

Verificando a Assinatura

Para garantir que o webhook veio do OctaBuild, verifique a assinatura:

import crypto from 'crypto';

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// No seu endpoint
app.post('/webhooks/octabuild', (req, res) => {
  const signature = req.headers['x-octabuild-signature'];
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    process.env.OCTABUILD_WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  const { event, data } = req.body;

  switch (event) {
    case 'land_plot.status_changed':
      console.log(`Terreno ${data.name}: ${data.previous_status} → ${data.status}`);
      break;
    case 'development.created':
      console.log(`Empreendimento criado: ${data.name}`);
      break;
    case 'financial.overdue':
      console.log(`Conta vencida: ${data.description}`);
      break;
  }

  res.status(200).send('OK');
});
import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

# No seu endpoint Flask
@app.route('/webhooks/octabuild', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-OctaBuild-Signature')
    is_valid = verify_webhook_signature(
        request.data.decode(),
        signature,
        os.environ['OCTABUILD_WEBHOOK_SECRET']
    )

    if not is_valid:
        return 'Invalid signature', 401

    event = request.json['event']
    data = request.json['data']

    if event == 'land_plot.status_changed':
        print(f"Terreno {data['name']}: {data['previous_status']}{data['status']}")

    return 'OK', 200

Política de Retry

Se sua aplicação não responder com 2xx dentro de 10 segundos, o OctaBuild tentará novamente:

TentativaIntervalo
Imediata
1 minuto
5 minutos
30 minutos
2 horas

Após 5 tentativas sem sucesso, o webhook é marcado como falho.

Boas Práticas

  1. Responda rápido — Retorne 200 OK imediatamente e processe o evento em background
  2. Seja idempotente — O mesmo evento pode ser entregue mais de uma vez
  3. Verifique a assinatura — Sempre valide o header X-OctaBuild-Signature
  4. Use HTTPS — Registre apenas URLs com HTTPS
  5. Monitore falhas — Acompanhe o dashboard de webhooks para identificar problemas

Suporte

On this page