Webhooks

Receba resultados da IA em tempo real via callback HTTP — sem polling.

Copiar como .md

Em vez de fazer polling pra saber se a IA terminou, configure um webhook e o BuildShip te chama quando o resultado fica pronto.

Configurar webhook

No painel API B2B → Webhooks, adicione um endpoint:

• URL: seu endpoint HTTPS (ex: https://seu-servidor.com/buildship/callback)
• Eventos: escolha quais (completion, error, etc)
• Secret: gerado automaticamente — use pra validar assinatura

Ou via API:

curl -X POST https://api.buildship.com.br/b2b/partners/SEU_ID/webhooks \
  -H "X-API-Key: bld_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seu-servidor.com/buildship/callback",
    "events": ["completion", "error"],
    "active": true
  }'

Payload

A IA chama seu endpoint com este JSON:

{
  "type": "completion",
  "sessionId": "session_abc123",
  "endUserId": "user-456",
  "templateId": "tmpl_xyz",
  "output": "Resposta final da IA",
  "status": "completed",
  "creditsUsed": 12,
  "tokensIn": 450,
  "tokensOut": 320,
  "timestamp": "2026-04-28T10:05:00Z"
}

Headers

Header	Descricao
X-Buildship-Signature	HMAC-SHA256 do body com seu secret
X-Buildship-Event	Tipo do evento (completion, error, etc)
X-Buildship-Delivery	UUID unico da entrega — use pra dedupe
User-Agent	BuildShip-Webhooks/1.0

Validar assinatura (HMAC-SHA256)

CRITICO pra seguranca — sem isso qualquer um pode forjar callbacks.

Node.js

import crypto from 'crypto';
import express from 'express';

const app = express();

app.post('/buildship/callback',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.header('X-Buildship-Signature');
    const expected = crypto
      .createHmac('sha256', process.env.BUILDSHIP_WEBHOOK_SECRET!)
      .update(req.body)
      .digest('hex');

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

    const event = JSON.parse(req.body.toString());
    console.log(`[buildship] ${event.type} session=${event.sessionId}`);

    // Processa o resultado
    if (event.type === 'completion') {
      // event.output tem a resposta
    }

    res.status(200).send('ok');
  }
);

Python (Flask)

import hmac, hashlib, os
from flask import Flask, request

app = Flask(__name__)
SECRET = os.environ['BUILDSHIP_WEBHOOK_SECRET']

@app.route('/buildship/callback', methods=['POST'])
def callback():
    signature = request.headers.get('X-Buildship-Signature')
    expected = hmac.new(
        SECRET.encode(),
        request.data,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        return 'Invalid signature', 401

    event = request.json
    print(f"[buildship] {event['type']} session={event['sessionId']}")

    return 'ok', 200

Eventos disponiveis

Evento	Quando
completion	IA terminou de processar — output tem resposta final
error	Falhou — error tem mensagem
session.started	Nova sessao criada
session.timeout	Sessao expirou (2h sem atividade)
tokens.exceeded	Limite de tokens do plano atingido

Retentativas

Se seu endpoint retornar nao-2xx, o BuildShip tenta novamente:

• Tentativa 1: imediata
• Tentativa 2: 30s depois
• Tentativa 3: 5min depois
• Tentativa 4: 30min depois
• Tentativa 5: 2h depois

Apos 5 falhas, o webhook e marcado como failed e voce recebe alerta no painel.

Testar webhook

No painel API B2B → Webhooks → Seu webhook → Testar, voce pode disparar um evento mock pra validar a integracao.

Ou via API:

curl -X POST https://api.buildship.com.br/b2b/webhooks/WEBHOOK_ID/test \
  -H "X-API-Key: bld_sua_chave"

Boas praticas

• Sempre valide a assinatura — caso contrario qualquer um pode forjar callbacks
• Use X-Buildship-Delivery pra dedupe — em retries voce vai receber o mesmo delivery ID
• Responda rapido (< 5s) — processe async se precisar de mais tempo
• HTTPS obrigatorio — webhooks HTTP nao sao aceitos
• Idempotencia — assuma que pode receber o mesmo evento mais de uma vez

Polling vs Webhooks

Polling	Webhooks
Voce chama GET /sessions/:id ate status=completed	BuildShip chama seu endpoint
Custa requests (rate limit)	Sem custo de requests
Pode demorar (intervalo de poll)	Em tempo real
Funciona em qualquer ambiente	Precisa endpoint HTTPS publico

Recomendacao: webhooks pra producao, polling pra dev/scripts.