Adding Inbound Webhooks

Adding an inbound webhook

Every webhook a third party sends to PostHog goes through posthog/ingress/. Read posthog/ingress/README.md for the transport contract and the package reference. This skill is the decision tree and the checklists.

Which job are you doing?

• The provider already has an endpoint (see the Endpoints table in posthog/ingress/README.md) and you want to react to its events: add a consumer.
• No endpoint exists for this third party, or the semgrep rule flagged a hand-rolled verifier: add a provider, then add its consumer.
• Outbound call to a vendor API, which is the other direction: /routing-outbound-api-calls.

Before you migrate a verifier, read what the existing code verifies with. A verifier the vendor ships in its SDK, or one from a maintained library, stays as it is: it is written by the people who define the scheme, and a reimplementation only adds bugs. Ingress wraps such a verifier at most. Only a hand-rolled hmac check is a migration.

Add a consumer

A product declares its consumers in products/<product>/backend/webhook_consumers.py, in a WEBHOOK_CONSUMERS sequence of WebhookConsumer values from posthog.ingress.contracts. products/stamphog/backend/webhook_consumers.py is the smallest complete example.

WEBHOOK_CONSUMERS = (
    WebhookConsumer(
        name="stamphog_review",
        provider="github",
        app="stamphog",
        event_types=frozenset({"pull_request"}),
        handler=_run_review,
    ),
)

Rules that decide whether this works:

• name is unique per provider and is part of the dedup cache key. Treat it as fixed once it ships: renaming one lets a redelivery run the consumer a second time.
• provider and app must match a ProviderSpec some incarnation declares, and event_types must be a subset of what that app declares. Anything else raises RegistryError when the registry is built, rather than sitting there looking registered and never running.
• handler takes one WebhookDelivery and returns nothing. Its return value is ignored and never decides the HTTP status. A handler that raises does cost the request its receipt when the provider sets retry_status, which is how a consumer whose durable record is written inside the handler gets the delivery again.
• Keep the module cheap to import. The registry imports it on the first delivery through load_product_modules("webhook_consumers"), so defer heavy imports into the handler behind # noqa: PLC0415 with a reason.
• The handler runs synchronously inside the request. Enqueue a task for real work, the way stamphog and conversations do.
• A handler that reads the database wraps the read in bounded_statement_timeout(ms, models=...) from posthog.ingress.dispatch.database, passing only the models the read actually uses. Opening an alias is itself unbounded, so naming one the read never touches can stall the delivery on connection setup.
• An import-linter contract (webhook consumers must only import facade) holds the module to its own product's facade/. Reach product internals through the facade. hogli product:lint holds the same rule by AST for every product that has a webhook_consumers.py, including relative imports and products with no contract yet.
• A consumer whose resources are split across regions declares ownership=, pointing at a facade function that returns a DeliveryOwnership. Ingress forwards the signed request when the answer is ELSEWHERE, and dispatches locally either way. The lookup runs inside the request, so bound it with bounded_statement_timeout(ms, models=...). Let a transient error out of the lookup rather than answering LOCAL or UNDECIDED through it: a lookup that raises asks a provider with retry_status for the delivery again, and a guessed answer receipts a delivery the other region never sees.
• A GitHub consumer cannot get its project from installation.id, because one installation can link to several projects. Read Picking the project for the two allowed shapes.

Tests: extend the product's existing webhook test module rather than starting a parallel one. products/stamphog/backend/tests/test_webhook_consumers.py is the shape: drive the real view with a signed RequestFactory request and assert the enqueue, plus the event type the app does not register, the bad signature, the unparseable body, the non-POST, and the missing secret. Reset the process-cached registry and the dedup cache between tests with reset_consumer_registry() and cache.clear().

Add a provider

Create posthog/ingress/<provider>/ with an __init__.py and a provider.py. Copy github/ for the full shape, or pandadoc/ for a small one. Copy the layout, not the behavior: a provider package holds only what is specific to its third party. A need that a second provider could share becomes a lane, a scheme option or a WebhookProvider attribute, the way retry_status and throttle_class did. A true one-off stays in the provider with a # One-off: comment that says why no other provider needs it. provider.py holds three things:

• SPECS, one ProviderSpec per app, naming the event types that app is subscribed to. The registry validates consumers against these.
• A WebhookProvider subclass with scheme() (from posthog/ingress/verify/), deliveries(request, payload, facts) (how to read the event type, delivery id and context off the verified request), and any status codes the provider's protocol fixes. Defaults are 403 on a bad signature, 500 when unconfigured, 202 on success.
  • verify(request) answers a Verification: the outcome, plus facts, whatever the scheme proved on the way. A scheme that validates a signed token puts its verified claims there and deliveries cross-checks the body against them; an HMAC scheme leaves it empty and deliveries ignores it.
  • parse(request) decodes the body, and defaults to JSON. Override it for a provider that posts a form, and raise InvalidPayload for a body it cannot read. Verification runs first and must, because reading request.POST consumes the request stream under ASGI.
  • throttle_class names a DRF throttle from posthog.rate_limit, run in front of verification. Set one when the endpoint is public and its verification is expensive, such as a JWT signing-key lookup.
  • retry_status is the status answered instead of the receipt when ingress cannot vouch that the delivery was accepted: an ownership lookup failed, the forward to the owning region failed, a consumer raised, or the budget skipped a consumer. Set it when the provider redelivers on a non-2xx, and leave it None when it does not, because the non-2xx then only loses the delivery. A retry replays the delivery against every consumer on the endpoint, and dedup is what stops the ones that already accepted it from running twice.
• A build_<provider>_provider(...) function returning it. Secrets and verifiers a product owns are passed into this builder, never imported: nothing under posthog/ingress/ may import a product. A builder that takes an app name calls require_known_app(provider, app, SPECS) from posthog/ingress/providers.py first, so a typo raises UnknownApp at import instead of serving an endpoint no consumer is registered against.

Picking a scheme

Three exist. Configure one; do not write a fourth without reading the Schemes section of the package README.

• HmacSha256 (verify/schemes.py) — a shared secret over the raw body. Covers hex or base64, an optional prefix, and the v0:{timestamp}:{body} input with a replay window that Slack and Customer.io sign. GitHub, Slack, PandaDoc and Customer.io all use it.
• SnsSignature (verify/schemes.py) — the AWS SNS envelope check plus a topic-ARN allowlist. The RSA work stays with a caller-supplied verifier.
• BearerJwt (verify/jwt.py) — a Bearer token signed as a JWT, checked against the issuer's published JWKS. Its facts are the verified claims. The incarnation supplies the JWKS URI, the audience and the issuer allowlist as callables, and caches any discovery it does to find the URI. An endpoint on this scheme sets throttle_class, because an unsigned request costs a signing-key lookup.

Then:

1. Add the module path to _INCARNATION_MODULES in posthog/ingress/providers.py, or the registry never sees its specs or core consumers.
2. Wire the URL with build_webhook_view() where the App registration lives. The owner of the third-party App owns the route: a product that registered the App declares webhook_urlpatterns in its own products/<product>/backend/routes.py, for example opt_slash_path("<provider>", build_webhook_view(build_<provider>_provider())). Core mounts that list at webhooks/<product>/, so the route is relative to it. Only an App several products consume stays in posthog/urls.py, which today is the customer-facing GitHub App alone. See docs/internal/url-routing.md.
3. Write posthog/ingress/<provider>/README.md with the fixed sections, in this order: headers, signature scheme, delivery id and event type, apps and secrets, quirks, consumers. posthog/ingress/test/test_provider_readme_sections.py fails on a provider folder without one, and on a README with different or reordered headings.
4. Add the provider's signature header name to the $HEADER regex in .semgrep/rules/devex/inbound-webhooks-go-through-ingress.yaml, plus a fixture case in the .py beside it. The header names are spelled out rather than matched generically because a generic header pattern makes semgrep time out on a large module, which drops that file from the scan without failing it.
5. Do not add the endpoint to paths.exclude in the same rule. Every verifier that predated ingress is migrated, so the rule has no grandfathered paths left.
6. Preserve the endpoint's externally observable behavior. Existing tests are the contract: move or extend them, do not drop assertions.

The DRF adapter path

An endpoint that genuinely needs DRF team scoping keeps its view and subclasses posthog.auth.WebhookSignatureAuthentication, which computes and compares through posthog/ingress/verify/schemes.py. Customer.io is the reference: team-scoped, secret from that team's integration row, no fan-out, so customerio/ contributes a scheme only and declares no spec. Everything else goes through build_webhook_view().

Non-goals

Ingress stores no delivery log, runs no queue, retry or dead letter of its own, lets no consumer decide the response, and promises no consumer order. It does answer retry_status when it cannot vouch that a delivery was accepted, which asks the provider's retry to run rather than adding one here. Each was a real proposal already; "Non-goals" in the package README records the reason for each one, so read it before proposing any of them again.

Verify

semgrep --config .semgrep/rules/devex/ .          # no hand-rolled verifier is left
semgrep --test .semgrep/                          # only if you changed the rule itself
lint-imports                                      # the webhook_consumers contract
hogli product:lint <product>                      # the AST backstop for that contract
hogli test products/<product>/backend/tests/test_webhook_consumers.py
hogli test posthog/ingress/test/
ruff check --fix <touched files> && ruff format <touched files>