Referencia técnica

API e webhooks para integrar GitHub ao DevLog AI.

Esta referencia mostra os endpoints públicos, headers esperados, validação de assinatura e respostas principais para quem vai configurar ou automatizar integrações.

Webhook GitHub por workspace

Receba eventos em um endpoint isolado por workspace.

POST /webhooks/github/{workspaceUuid}
Content-Type: application/json
X-GitHub-Event: push
X-GitHub-Delivery: 8189e9a8-43cc-11f1-8719-a9d9d4b439df
X-Hub-Signature-256: sha256=...

workspaceUuid

Identificador público do workspace. Ele aparece no painel do usuário autenticado.

Secret

O segredo do workspace deve ser configurado no GitHub para gerar a assinatura HMAC SHA-256.

Payload

O corpo JSON e armazenado de forma sanitizada e aparece no histórico privado do workspace.

Validacao de assinatura

Assinatura invalida deve falhar antes de salvar o evento.

expected = "sha256=" + HMAC_SHA256(rawBody, workspaceSecret)
valid = hash_equals(expected, X-Hub-Signature-256)

Se a assinatura não existir ou não bater, o endpoint retorna 401 e o payload não entra no workspace.

Respostas comuns

200 OK

{"ok": true, "id": 123}

Evento aceito, validado e salvo.

401 Unauthorized

{"error": "Assinatura GitHub invalida."}

Secret incorreto ou assinatura ausente.

429 Too Many Requests

{"error": "Limite mensal de eventos atingido."}

Workspace atingiu o limite do plano.

GitHub App

O caminho oficial para produção usa GitHub App.

POST /webhooks/github-app
X-GitHub-Event: push
X-Hub-Signature-256: sha256=...

O endpoint de GitHub App valida o secret global do app, encontra a instalacao pelo installation.id e salva o evento no workspace vinculado.

Mercado Pago

Billing recebe notificacoes assinadas do provedor.

POST /webhooks/mercado-pago
x-signature: ...
x-request-id: ...

Esse endpoint processa eventos de pagamento, assinaturas e faturas de uso quando o secret do webhook está configurado.

Boas práticas

Use HTTPS

Webhooks de produção devem apontar para dominio oficial com TLS ativo.

Rotacione secrets

Se houver suspeita de exposicao, gere um novo secret no painel e atualize o GitHub.

Evite dados desnecessários

Revise eventos e repositórios para não enviar payloads alem do necessário.