Webhooks

Overview

The eu_tools app exposes webhook endpoints for external services to push events into Alan's internal systems. Each webhook validates the incoming request's authenticity, parses the payload, and dispatches to one or more handlers — often enqueueing background jobs for heavier processing.

Endpoint summary

Method	Path	Source	Auth Type	Description
POST	/webhooks/linear	Linear	sha256_raw	Issue/comment events → SLA, assignment, Intercom notes, oncall reminders
POST	/webhooks/intercom	Intercom	sha1	Conversation events → Linear issue creation, command routing
POST	/webhooks/github/actions	GitHub	sha256	Workflow failures and deployment tracking
POST	/webhooks/github/pull-requests	GitHub	sha256	PR events → Slack notifications, compliance checks
POST	/webhooks/datadog	Datadog	basic	Alert notifications → Slack routing
POST	/webhooks/docusign	DocuSign	sha256_base64	Envelope lifecycle → Google Drive upload
POST	/webhooks/google/calendar	Google Calendar	secret	Calendar changes → oncall shift decline handling
POST	/webhooks/incident/lead	Incident.io	svix	Incident lead assignment
POST	/webhooks/cloudflare/pages	Cloudflare Pages	secret	Deployment sync → GitHub PR comments
POST	/webhooks/qovery	Qovery	secret	Deployment events → notifications, GitHub PR comments
POST	/webhooks/notifications/kay	Internal (Kay)	Basic Auth	Kay alert dispatch
POST	/webhooks/notifications	Internal	Basic Auth	Generic Slack notification dispatcher
POST	/webhooks/sales-prospecting/summary	Internal	API key	Salesforce account summary generation
POST	/webhooks/sales-prospecting/dust	Internal	API key	Dust AI sales conversation
GET	/webhooks/sales-prospecting/job/<job_id>	Internal	API key	Async job status polling

Authentication

All external webhooks use WebhookAuthContextProvider from the shared IAM layer. The provider validates the request signature or secret, then sets a ServiceAccount as the authenticated principal.

Supported auth types

Auth type	Mechanism	Used by
sha1	HMAC-SHA1 signature in header	Intercom
sha256	HMAC-SHA256 hex digest in header	GitHub Actions, GitHub PRs
sha256_raw	HMAC-SHA256 raw signature in header	Linear
sha256_base64	HMAC-SHA256 base64-encoded signature in header	DocuSign
basic	HTTP Basic Auth (username + password)	Datadog
secret	Shared secret token in header	Google Calendar, Cloudflare, Qovery
svix	Svix signature verification (timestamp + signatures)	Incident.io

For implementation details, see the IAM Webhook Authentication docs and the OpenAPI reference ⧉.

Common patterns

Handler registry (Linear)

The Linear webhook dispatches events through an ordered list of handler classes, each implementing a handle(event) method. Handlers are processed sequentially; each decides independently whether to act on the event.

Topic routing (Intercom)

Intercom payloads include a topic field. The webhook maps topics to handler classes via a TOPIC_HANDLERS dict, skipping unrecognized topics.

Async enqueueing

Several webhooks enqueue background jobs (via RQ) for heavy processing — Google Calendar sync, DocuSign document upload, Qovery deployment processing, sales prospecting.

Idempotency

The @webhook_request_handler decorator (used by Datadog, Qovery, Cloudflare, Notifications) persists payloads to DB and deduplicates by checksum, preventing duplicate processing.

Request flow

sequenceDiagram
    participant Ext as External Service
    participant WH as Webhook Endpoint
    participant Auth as WebhookAuthContextProvider
    participant Handler as Handler(s)
    participant Queue as Background Queue

    Ext->>WH: POST /webhooks/<service>
    WH->>Auth: Validate signature/secret
    Auth-->>WH: ServiceAccount context

    alt Sync processing
        WH->>Handler: Dispatch event
        Handler-->>WH: Result
    else Async processing
        WH->>Queue: Enqueue job
    end

    WH-->>Ext: 200/204 Response

Hold "Alt" / "Option" to enable pan & zoom