Docs · Webhooks

Webhooks: o desenho está aqui — a feature ainda não

Nenhum webhook do GenOpt dispara hoje. Esta página publica o desenho planejado (Sprint 4E) para colher crítica antes de escrever o código — não para fingir que existe. Quando entrar no ar, o estado muda aqui e no /changelog.

Estado: planejado — Sprint 4E

Não há endpoint para cadastrar URL, não há evento sendo emitido e não há segredo para gerar. Tudo abaixo é desenho sujeito a mudança até a primeira emissão real. Previsão pública no /roadmap.

O desenho: entrega assinada com HMAC

Cada entrega será um POST JSON na URL que você cadastrar, assinada com HMAC-SHA256 sobre o corpo bruto mais um timestamp — o mesmo padrão de Stripe e GitHub, escolhido porque os seus desenvolvedores provavelmente já o verificaram uma vez na vida. O segredo de assinatura será exibido uma única vez no cadastro e armazenado como hash do nosso lado, como já fazemos com evidência.

Entrega planejada (desenho, não contrato)

POST https://sua-url.exemplo.com/genopt
Content-Type: application/json
X-GenOpt-Event: measurement.completed
X-GenOpt-Timestamp: 1770854400
X-GenOpt-Signature: sha256=3f2a...c91b

{
  "event": "measurement.completed",
  "occurred_at": "2026-08-07T12:00:00Z",
  "data": {
    "brand_id": "…",
    "engine": "…",
    "run_count": 0
  }
}

Verificação da assinatura (desenho, não contrato)

// Verificação no seu servidor (Node, desenho):
import { createHmac, timingSafeEqual } from 'node:crypto'

const esperado = createHmac('sha256', process.env.GENOPT_WEBHOOK_SECRET)
  .update(`${timestamp}.${corpoBruto}`)
  .digest('hex')

// compare com timingSafeEqual e rejeite timestamps com mais de 5 minutos

Eventos planejados

A primeira leva cobre o que os clientes pedem para não precisar ficar olhando o painel: medição concluída, confabulação nova detectada e mudança de classificação de citação. Retentativa com backoff exponencial em falha de entrega, e rejeição recomendada de timestamps velhos para bloquear replay. Os nomes finais dos eventos saem junto com a implementação — publicar nome de evento antes do código é convidar integração quebrada.

Enquanto isso, o que existe de verdade

Para consumo programático hoje: a API v1 documentada em /docs/api (pull, não push) e o servidor MCP no ar em mcp.genopt.ai, documentado em /docs/mcp. O estado de todas as integrações, com rótulo honesto, está em /integracoes.