Skip to content

: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.

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.py
index 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-ingress
expected = 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.yaml
index 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.md
index 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.md
new file mode 100644
index 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__.py
new file mode 100644
index 000000000000..e69de29bb2d1
diff --git a/posthog/ingress/linear/provider.py b/posthog/ingress/linear/provider.py
new file mode 100644
index 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.py
index 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.py
new file mode 100644
index 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.py
index 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_SECRE
LINEAR_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.py
index 4bf46e2bff5a..61c9152032eb 100644
--- a/posthog/urls.py
+++ b/posthog/urls.py
@@ -34,6 +34,7 @@ from posthog.api.web_experiment import web_experiments
from posthog.ee_urls import ee_urlpatterns
from posthog.frontend_views import app_context, home, home_with_region_redirect
from posthog.ingress.github.provider import build_github_provider
+from posthog.ingress.linear.provider import build_linear_provider
from posthog.ingress.views import build_webhook_view
from posthog.oauth2_urls import urlpatterns as oauth2_urls
from 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 preferences
path("messaging-preferences/<str:token>/", preferences_page, name="message_preferences"),
opt_slash_path("messaging-preferences/update", update_preferences, name="message_preferences_update"),