Webhooks

Inbound (GitHub & Linear)

Inbound webhooks create memories automatically for an organization.

Setup (dashboard)

1. Sign in as an owner at /app.
2. Open Integrations for your organization.
3. Click Add GitHub webhook and copy the URL and secret when shown.
4. In GitHub → repository → Settings → Webhooks, paste the URL, set content type to application/json, and paste the secret.
5. Enable events: push and/or issues.

Endpoint

POST /webhooks/github/{webhookId}

Headers (GitHub default):

• X-Hub-Signature-256: HMAC SHA-256 of the raw body
• X-GitHub-Event: e.g. push, issues
• X-GitHub-Delivery: unique delivery id (used for idempotency metadata)

Invalid signatures return 401. Accepted payloads are queued and ingested with metadata { source: "github", project: "{owner}/{repo}", ... }.

Content scanning (OB-045) and audit logging (OB-047) apply to webhook ingest like API ingest.

Inbound ingest is a write: when billing enforcement is on and the organization is unpaid (or over its ingest cap), the queued job is dropped without retry. No memory row and no usage is recorded, and the delivery is counted as a failed inbound webhook in metrics. See Billing and usage.

Linear ingest

1. In Integrations, click Add Linear webhook and copy the URL and secret.
2. In Linear → Settings → API → Webhooks, add the URL and signing secret.
3. Subscribe to Issue and/or Comment events (must match the events selected in the OpenBrain dashboard).

POST /webhooks/linear/{webhookId}

• Header Linear-Signature: hex HMAC-SHA-256 of the raw body
• Header Linear-Delivery: delivery id (stored in metadata)
• Body type: Issue, Comment, etc.

Invalid signatures return 401.

Outbound (customer notifications)

Owners can register HTTPS endpoints that receive signed JSON when memories change.

Setup

1. Integrations → Add outbound webhook
2. Choose events: memory.ingested, memory.updated, memory.deleted
3. Copy the signing secret (shown once)

Delivery

OpenBrain POSTs to your URL with:

• X-OpenBrain-Event: event name
• X-OpenBrain-Signature: sha256= HMAC of the raw JSON body

Payload (no raw memory content by default):

{
  "event": "memory.ingested",
  "timestamp": "2026-05-22T12:00:00+00:00",
  "payload": {
    "id": "thought-uuid",
    "outcome": "created",
    "metadata": { "source": "api", "project": "my-app" }
  }
}

Failed deliveries retry up to three times via the queue worker.