:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(ingress): add a linear provider (#125472)
Aleksander Błaszkiewicza9f629fb9cec
diff --git a/.semgrep/rules/devex/inbound-webhooks-go-through-ingress.py b/.semgrep/rules/devex/inbound-webhooks-go-through-ingress.pyindex 2a89d26bb12c..c2276b2daa91 100644--- a/.semgrep/rules/devex/inbound-webhooks-go-through-ingress.py+++ b/.semgrep/rules/devex/inbound-webhooks-go-through-ingress.py@@ -74,6 +74,16 @@ def naive_compare_view(request: HttpRequest) -> HttpResponse:return HttpResponse(status=202)+def linear_header_view(request: HttpRequest) -> HttpResponse:+ signature = request.headers.get("Linear-Signature", "")+ # ruleid: inbound-webhooks-go-through-ingress+ expected = hmac.new(b"secret", request.body, hashlib.sha256).hexdigest()+ # ruleid: inbound-webhooks-go-through-ingress+ if not hmac.compare_digest(expected, signature):+ return HttpResponse(status=403)+ return HttpResponse(status=200)++def verify_pandadoc_signature(body: bytes, signature: str, secret: str) -> bool:# ruleid: inbound-webhooks-go-through-ingressexpected = hmac.digest(secret.encode(), body, hashlib.sha256)diff --git a/.semgrep/rules/devex/inbound-webhooks-go-through-ingress.yaml b/.semgrep/rules/devex/inbound-webhooks-go-through-ingress.yamlindex 71f4c9b335b3..edbae0e356bb 100644--- a/.semgrep/rules/devex/inbound-webhooks-go-through-ingress.yaml+++ b/.semgrep/rules/devex/inbound-webhooks-go-through-ingress.yaml@@ -72,7 +72,7 @@ rules:...- metavariable-regex:metavariable: $HEADER- regex: (?i)^["'](http[_-])?(x[_-](hub[_-]signature[_-]256|slack[_-]signature|pandadoc[_-]signature|cio[_-]signature|vapi[_-]signature|vercel[_-]signature)|stripe[_-]signature)["']$+ regex: (?i)^["'](http[_-])?(x[_-](hub[_-]signature[_-]256|slack[_-]signature|pandadoc[_-]signature|cio[_-]signature|vapi[_-]signature|vercel[_-]signature)|stripe[_-]signature|linear[_-]signature)["']$# The verifier often sits in its own module, away from the header read, so# catch it by what it is called. Both name shapes a verifier takes: a verb# first (`verify_signature`), or a predicate (`signature_ok`,diff --git a/posthog/ingress/README.md b/posthog/ingress/README.mdindex 6018048482a8..7caabbdaedbe 100644--- a/posthog/ingress/README.md+++ b/posthog/ingress/README.md@@ -79,6 +79,7 @@ Three duties fall on the incarnation rather than on `BearerJwt`, and none is enf| `sns` | `/webhooks/workflows/ses-events` | `default` | `workflows_ses_events` | `products/workflows/backend/webhook_consumers.py` || `customerio` | `/api/projects/<team_id>/messaging/customerio/webhook/` | none | none, it is the DRF adapter path | `products/messaging/backend/api/customerio_webhook.py` || `vercel` | `/webhooks/vercel` | `marketplace` | `vercel_marketplace` | `ee/api/vercel/webhook_consumers.py` |+| `linear` | `/webhooks/linear` | `posthog` | none | none |The owner of the third-party App registration owns the route.The customer-facing GitHub App is shared across products, so its two endpoints are declared in `posthog/urls.py`.@@ -260,7 +261,7 @@ webhook_urlpatterns: list[URLPattern] = [The route is relative to the mount, so this one serves `/webhooks/stamphog/github`.An App several products consume has no single owner, so it stays in `posthog/urls.py`.-The customer-facing GitHub App is the only one today.+The customer-facing GitHub App and the Linear App are the cases.[docs/internal/url-routing.md](../../docs/internal/url-routing.md) has the slot and the prefix rule.Secrets and verifiers that belong to a product are **passed into the builder**.diff --git a/posthog/ingress/linear/README.md b/posthog/ingress/linear/README.mdnew file mode 100644index 000000000000..20f265bc146c--- /dev/null+++ b/posthog/ingress/linear/README.md@@ -0,0 +1,56 @@+# Linear++Deliveries from the PostHog Linear OAuth App.++## Headers++- `Linear-Signature` carries the signature.+- `Linear-Delivery` carries the delivery id.+- `Linear-Event` carries the event type.++Linear also sends `Linear-Timestamp`.+It is not covered by the signature, so nothing reads it.++## Signature scheme++HMAC-SHA256 over the raw body, hex encoded, with no prefix.+A signature that is not 64 lowercase hex characters is refused before the HMAC runs.++The replay window is read from `webhookTimestamp` in the body, a UNIX timestamp in milliseconds.+A body sent more than 60 seconds before or after it arrives answers 400, which is the window Linear recommends.+The check runs in `deliveries`, after verification, because the scheme only reads headers before the body.+Linear's own SDK verifier (`packages/sdk/src/webhooks/client.ts` in `linear/linear`) applies the same 60-second window to the signed `webhookTimestamp`.+So a redelivery carries a new timestamp, or no receiver built on that SDK could accept one.++## Delivery id and event type++Both come from headers, never from the body.+A request without `Linear-Delivery` gets no delivery id and skips dedup.+The payload's `organizationId` goes into the delivery context as `organization_id`.+It is the Linear workspace id, which is also the `integration_id` of a `linear` integration row.++## Apps and secrets++One app, `posthog`, the Linear OAuth App that the `linear` integration connects through.+Its secret is the signing secret from the App's webhook settings in Linear, read as `LINEAR_APP_WEBHOOK_SECRET`.+It is a plain env var on the Django pods, wired from `posthog-django-shared-secrets` the way `VERCEL_CLIENT_INTEGRATION_SECRET` is.+It stays off the credentials service, because every deployment that holds a caller key can read any entry there, and an inbound signing secret must not be that widely readable.++The App's webhook settings subscribe to the `Issue` resource type.+Linear creates the webhook for a workspace when the workspace authorizes the App, so a workspace that authorized it before the webhook settings existed gets deliveries only after it connects again.++One Linear App serves both regions.+Its webhook URL names the primary region, `https://eu.posthog.com/webhooks/linear`, so every delivery arrives there first.++## Quirks++Success answers 200, not the default 202, because Linear counts any other status as a failed delivery.+Linear retries a failed delivery after 1 minute, 1 hour and 6 hours, and it can disable a webhook that keeps failing.+`retry_status` is 500, so a consumer that raised or that the request budget skipped asks for that retry.+A missing secret answers 403 rather than 500, because a self-hosted deployment may never set up the Linear App.+Rejections carry an empty body, so a caller cannot tell a missing secret from a bad signature.++## Consumers++None. The endpoint verifies each delivery and answers 200, and nothing acts on it.+See the [Endpoints table](../README.md#endpoints).diff --git a/posthog/ingress/linear/__init__.py b/posthog/ingress/linear/__init__.pynew file mode 100644index 000000000000..e69de29bb2d1diff --git a/posthog/ingress/linear/provider.py b/posthog/ingress/linear/provider.pynew file mode 100644index 000000000000..9a836c9a43fc--- /dev/null+++ b/posthog/ingress/linear/provider.py@@ -0,0 +1,93 @@+"""Linear OAuth App deliveries.++Linear creates one webhook per workspace that authorizes the PostHog Linear App, and every one of+them posts to the URL in the App's webhook settings, signed with the App's one signing secret.+"""++import re+import time+from collections.abc import Mapping, Sequence+from typing import Any++from django.conf import settings+from django.http import HttpRequest+from django.utils import timezone++from posthog.ingress.contracts import ProviderSpec, WebhookDelivery+from posthog.ingress.providers import InvalidPayload, WebhookProvider, require_known_app+from posthog.ingress.verify.schemes import HmacSha256, SignatureScheme++LINEAR_EVENT_TYPES = frozenset({"Issue"})++LINEAR_SIGNATURE_HEADER = "Linear-Signature"++# Linear recommends that a receiver refuses a body sent more than a minute before it arrives.+_MAX_TIMESTAMP_SKEW_SECONDS = 60++SPECS = (ProviderSpec(provider="linear", app="posthog", event_types=LINEAR_EVENT_TYPES),)+++# An inbound signing secret stays off the credentials service, because every deployment that holds+# a caller key can read any entry there. It is a plain env var on the pods that check it.+def _posthog_app_secret() -> str | None:+ return getattr(settings, "LINEAR_APP_WEBHOOK_SECRET", "") or None+++def _timestamp_is_fresh(payload: Mapping[str, Any]) -> bool:+ timestamp_ms = payload.get("webhookTimestamp")+ if isinstance(timestamp_ms, bool) or not isinstance(timestamp_ms, int | float):+ return False+ return abs(time.time() - timestamp_ms / 1000) <= _MAX_TIMESTAMP_SKEW_SECONDS+++class LinearProvider(WebhookProvider):+ provider = "linear"+ # Linear counts only a 200 as delivered. It retries anything else and can disable a webhook+ # that keeps failing, so the default 202 receipt would look like an outage to Linear.+ success_status = 200+ # Linear redelivers after a non-200 (after 1 minute, 1 hour and 6 hours), so a delivery that+ # ingress cannot vouch for asks for that retry instead of being receipted and lost.+ retry_status = 500+ # A self-hosted deployment may never set up the Linear App, so a missing secret must not+ # answer a server error to every anonymous probe of the public URL.+ unconfigured_status = 403+ # The body must not tell an unauthenticated caller that the endpoint is unconfigured, which is+ # an operator fact about an instance anyone can probe.+ explains_rejections = False++ def __init__(self, app: str) -> None:+ require_known_app(self.provider, app, SPECS)+ self.app = app+ self._scheme = HmacSha256(+ secret_getter=_posthog_app_secret,+ signature_header=LINEAR_SIGNATURE_HEADER,+ signature_pattern=re.compile(r"^[0-9a-f]{64}$"),+ )++ def scheme(self) -> SignatureScheme:+ return self._scheme++ def deliveries(self, request: HttpRequest, payload: Any, facts: Mapping[str, Any]) -> Sequence[WebhookDelivery]:+ if not isinstance(payload, Mapping):+ return ()+ # One-off: Linear puts its replay timestamp inside the signed body, not in a signed+ # header, so the scheme cannot check it. The `Linear-Timestamp` header carries the same+ # value but is not covered by the signature, so it proves nothing.+ if not _timestamp_is_fresh(payload):+ raise InvalidPayload("webhookTimestamp is missing or outside the replay window")+ organization_id = payload.get("organizationId")+ return (+ WebhookDelivery(+ provider=self.provider,+ app=self.app,+ delivery_id=request.headers.get("Linear-Delivery") or None,+ event_type=request.headers.get("Linear-Event", ""),+ payload=payload,+ received_at=timezone.now(),+ context={"organization_id": organization_id} if isinstance(organization_id, str) else {},+ ),+ )+++def build_linear_provider(app: str) -> LinearProvider:+ return LinearProvider(app)diff --git a/posthog/ingress/providers.py b/posthog/ingress/providers.pyindex e9af5e50c133..4e7c1941cf2d 100644--- a/posthog/ingress/providers.py+++ b/posthog/ingress/providers.py@@ -30,6 +30,7 @@ _INCARNATION_MODULES = ("posthog.ingress.mailgun.provider","posthog.ingress.sns.provider","posthog.ingress.vercel.provider",+ "posthog.ingress.linear.provider",)diff --git a/posthog/ingress/test/test_linear.py b/posthog/ingress/test/test_linear.pynew file mode 100644index 000000000000..bef89c3e6cc6--- /dev/null+++ b/posthog/ingress/test/test_linear.py@@ -0,0 +1,68 @@+import hmac+import json+import time++from django.core.cache import cache+from django.test import RequestFactory, SimpleTestCase, override_settings++from parameterized import parameterized++from posthog.ingress.dispatch.loading import reset_consumer_registry+from posthog.ingress.linear.provider import build_linear_provider+from posthog.ingress.views import build_webhook_view++SECRET = "linear-app-secret"+++def _body(timestamp_ms: int | None) -> bytes:+ payload: dict[str, object] = {"type": "Issue", "action": "create", "organizationId": "org-1", "data": {}}+ if timestamp_ms is not None:+ payload["webhookTimestamp"] = timestamp_ms+ return json.dumps(payload).encode()+++class TestLinearProvider(SimpleTestCase):+ def setUp(self) -> None:+ reset_consumer_registry()+ cache.clear()+ self.addCleanup(reset_consumer_registry)+ self.addCleanup(cache.clear)++ @parameterized.expand(+ [+ ("fresh", 0, SECRET, SECRET, 200),+ ("clock_skew_inside_the_window", -30, SECRET, SECRET, 200),+ ("replayed_after_the_window", -120, SECRET, SECRET, 400),+ ("sent_from_the_future", 120, SECRET, SECRET, 400),+ ("no_timestamp", None, SECRET, SECRET, 400),+ ("wrong_secret", 0, "another-secret", SECRET, 403),+ ("secret_unset", 0, SECRET, "", 403),+ ]+ )+ def test_answers_only_a_fresh_correctly_signed_body_with_the_200_linear_requires(+ self,+ _name: str,+ offset_seconds: int | None,+ signing_secret: str,+ configured_secret: str,+ expected_status: int,+ ) -> None:+ timestamp_ms = None if offset_seconds is None else int((time.time() + offset_seconds) * 1000)+ body = _body(timestamp_ms)+ request = RequestFactory().post(+ "/webhooks/linear/",+ data=body,+ content_type="application/json",+ headers={+ "Linear-Signature": hmac.digest(signing_secret.encode(), body, "sha256").hex(),+ "Linear-Delivery": "delivery-1",+ "Linear-Event": "Issue",+ },+ )++ with override_settings(LINEAR_APP_WEBHOOK_SECRET=configured_secret):+ response = build_webhook_view(build_linear_provider("posthog"))(request)++ self.assertEqual(response.status_code, expected_status)+ if expected_status == 403:+ self.assertEqual(response.content, b"")diff --git a/posthog/settings/integrations.py b/posthog/settings/integrations.pyindex 9485fc4cdf5a..8f2d7c268d4b 100644--- a/posthog/settings/integrations.py+++ b/posthog/settings/integrations.py@@ -67,6 +67,8 @@ SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET = get_from_env("SOCIAL_AUTH_GOOGLE_OAUTH2_SECRELINEAR_APP_CLIENT_ID = get_from_env("LINEAR_APP_CLIENT_ID", "")LINEAR_APP_CLIENT_SECRET = get_from_env("LINEAR_APP_CLIENT_SECRET", "")+# The signing secret from the Linear App's webhook settings. Empty leaves `webhooks/linear` unconfigured.+LINEAR_APP_WEBHOOK_SECRET = get_from_env("LINEAR_APP_WEBHOOK_SECRET", "")HELPSCOUT_APP_CLIENT_ID = get_from_env("HELPSCOUT_APP_CLIENT_ID", "")HELPSCOUT_APP_CLIENT_SECRET = get_from_env("HELPSCOUT_APP_CLIENT_SECRET", "")diff --git a/posthog/urls.py b/posthog/urls.pyindex 4bf46e2bff5a..61c9152032eb 100644--- a/posthog/urls.py+++ b/posthog/urls.py@@ -34,6 +34,7 @@ from posthog.api.web_experiment import web_experimentsfrom posthog.ee_urls import ee_urlpatternsfrom posthog.frontend_views import app_context, home, home_with_region_redirectfrom posthog.ingress.github.provider import build_github_provider+from posthog.ingress.linear.provider import build_linear_providerfrom posthog.ingress.views import build_webhook_viewfrom posthog.oauth2_urls import urlpatterns as oauth2_urlsfrom posthog.product_urls import ProductRootRoutes@@ -359,6 +360,8 @@ urlpatterns = [# It stays in core because the App is shared: no single product owns its registration.opt_slash_path("webhooks/github/pr", github_app_webhook),opt_slash_path("webhooks/github", github_app_webhook),+ # Linear App webhook. It stays in core for the same reason: the Linear integration is shared.+ opt_slash_path("webhooks/linear", build_webhook_view(build_linear_provider("posthog"))),# Message preferencespath("messaging-preferences/<str:token>/", preferences_page, name="message_preferences"),opt_slash_path("messaging-preferences/update", update_preferences, name="message_preferences_update"),