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: ```bash 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: ```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 ```ts 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) ```python 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: ```bash 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 /chat/:sessionId` 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.