Webhooks & API

Molar Guard exposes a Fastify REST API at https://api.molar.it/v1 (or http://localhost:4000/v1 locally), GitHub webhooks for PR automation, Server-Sent Events for live logs, and an MCP server for AI agent integration.

OpenAPI spec: GET /v1/openapi.json on your Guard API host.

Authentication

Create API keys: app.molar.it → Settings → API keys.

API keys support scoped permissions (mcp:read, mcp:write, mcp:run, scheduled_checks:manage, etc.).

GitHub webhooks (inbound)

Guard receives GitHub App events at:

POST https://api.molar.it/v1/webhooks/github

Security

Every delivery is validated before processing:

• HMAC-SHA256 signature (X-Hub-Signature-256) via webhook secret
• Replay prevention: delivery ID stored in Redis (SETEX guard:webhook:delivery:{id} 86400 1, NX)
• Body size limit: 25 MB
• Timestamp skew: reject deliveries older than 10 minutes

Subscribed events

pull_request, push, check_run, check_suite, installation, installation_repositories, pull_request_review

Typical flow

GitHub → POST /v1/webhooks/github
      → verify + dedupe
      → enqueue BullMQ (guard-pr | guard-schedule | mender)
      → 200 OK within seconds
      → worker processes asynchronously

If GH_APP_ID is unset (plug-and-play mode), GitHub webhooks are ignored — use the GitHub Action + API key path instead.

Outbound webhooks (alerts)

Configure generic webhooks in Settings → Notifications. Guard POSTs JSON on:

• Incident opened / resolved
• PR gate failure (optional)
• Mender PR opened
• Shadow-prod diff detected

Payload shape (example):

{
  "event": "incident.opened",
  "orgId": "00000000-0000-0000-0000-000000000001",
  "incidentId": "…",
  "scenarioSlug": "stripe-subscription-upgrade",
  "region": "us-east-1",
  "runId": "…",
  "failureSignature": "step-7: assertion .subscription-status",
  "traceUrl": "https://trace.molar.it/…",
  "timestamp": "2026-05-19T14:22:00Z"
}

Verify webhook authenticity via shared secret in notification settings (HMAC on request body).

REST API reference

Base URL: https://api.molar.it/v1

Runs

Manual run example:

curl -X POST https://api.molar.it/v1/runs/manual \
  -H "Authorization: Bearer $MOLAR_API_KEY" \
  -H "x-org-id: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "scenarioId": "00000000-0000-0000-0000-000000000001",
    "region": "us-east-1",
    "baseUrl": "https://staging.example.com"
  }'

SSE logs:

curl -N https://api.molar.it/v1/runs/$RUN_ID/logs \
  -H "Authorization: Bearer $MOLAR_API_KEY" \
  -H "x-org-id: $ORG_ID"

Scheduled checks

Incidents

Mender

Scenarios & affected detection

Monitoring & status

Onboarding

Org & billing

Audit

Error responses

Standard shape:

{ "error": "<code>", "message": "<human explanation>" }

Common codes: 401 Unauthorized, 403 Forbidden, 429 Quota Exceeded, 429 Too Many Requests, 422 validation, 503 unavailable.

Full reference: Error codes

MCP server

Guard also publishes a standalone MCP server (stdio transport) with org-scoped API key auth:

Resources

Tools (standalone Guard MCP)

The unified Molar MCP connector at mcp.molar.cloud (via molar-platform/packages/guards-mcp) exposes additional tools — molar_get_run, molar_get_mender_attempts, molar_run_scenarios, etc. — proxied through the Molar API.

Capability manifest: docs.molar.it/.well-known/molar-capabilities.json

MCP auth

Org API key with MCP scopes, or OAuth2 via the Molar API (mcp:read, mcp:write, mcp:run). MCP credentials do not use dashboard session cookies.

Rate limits

• GitHub API calls: Octokit throttling + retry (per installation)
• Guard REST: per-IP and per-org limits; honor Retry-After on 429
• Webhook processing: per-installation BullMQ partition prevents noisy-neighbor starvation

Health & metrics

SDKs and CLI

No official language SDK yet — use REST + API key. OpenAPI client generation supported via /v1/openapi.json.

Next

• Configuration — environment variables
• Security — API key scopes and RBAC
• Troubleshooting — webhook delivery failures