API

Webhooks

Inbound provider webhooks ProductOS receives, and the planned shape of outbound event subscriptions.

Webhooks run in two directions: inbound (available: other services notify ProductOS) and outbound (planned: ProductOS notifying your service).

Inbound

ProductOS receives inbound webhooks on two kinds of URL. The GitHub App delivers every workspace's events to /api/integrations/github/webhook; the App's own configuration points at it, so there is nothing for you to set up once GitHub is connected. Per-workspace endpoints at /api/webhooks/{provider}/{workspaceId} accept Linear, GitHub issue and Jira deliveries verified against a per-workspace secret; these are not yet configurable from Settings.

How signatures are verified

Each delivery is verified against the secret ProductOS holds for that connection before anything runs:

Provider	Algorithm	Header
GitHub	HMAC-SHA256	`X-Hub-Signature-256`
Linear	HMAC-SHA256	`Linear-Signature`
Jira	Shared secret (Jira sends no signature)	`?secret=` query parameter

A delivery that fails verification is rejected with 401 and never runs a handler. Deliveries to the per-workspace endpoints, accepted or rejected, are recorded in the integration health log. There is no timestamp check on inbound deliveries; replay protection rests on the secret and HTTPS.

Event mapping

Each connector maps what it receives or syncs to ProductOS state changes. For the precise mapping per provider see:

Side-effect: notifications

Beyond syncing state, the GitHub webhook emits an in-app notification when a delivered event matches a user-relevant change. Specifically, pull_request deliveries fan out to:

pr.merged_for_my_feature: when a PR is merged and its URL is attached to a feature (a github_pr document link) that you lead or are assigned to

Delivery channels (in-app bell, email; the Slack column is saved but does not deliver yet) are governed per-user from Settings → Notifications. Other inbound providers don't emit notification events today.

Outbound (not yet available)

Outbound webhook subscriptions are on the roadmap but not available yet, and no release date is committed. Today you can poll the API or read changes through the MCP server. What follows is a preview of the intended design and may change before it ships. The planned event types:

Event	Fires when
`feedback.created`	New feedback row arrives (any source)
`feedback.linked`	Feedback gets linked to a theme or feature
`theme.promoted`	A theme is promoted into a feature
`feature.shipped`	Feature flips to `status = shipped`
`release.published`	A release with `is_public = true` is published
`outcome.recorded`	Outcome is finalized (result + learning fields filled)

Subscriptions will be created through a /api/v1/ endpoint and signed with HMAC-SHA256 in X-ProductOS-Signature plus X-ProductOS-Timestamp; the exact shape is not final.

Authentication: how to authenticate outbound polling.
Connecting GitHub: the most-used inbound webhook integration.