Webhook Ingest

The webhook ingest gateway receives events from external providers (Linear, GitHub, Vercel, GitHub Actions) and routes them through Rensei's workflow engine. All ingest endpoints return an immediate 200 ACK - routing, execution, and side effects run asynchronously after response.

Ingest URL

POST /api/webhooks/ingest/{provider}

Supported providers: linear, github, github-actions, vercel

Example (Linear webhook URL):

https://app.rensei.ai/api/webhooks/ingest/linear

GitHub is the exception to the manual-setup pattern below: GitHub App webhook deliveries are managed automatically at the App level and arrive on the dedicated /api/webhook/github endpoint. The GitHub integration does not issue per-organization webhook secrets - see the GitHub integration for how events are routed.

Response format

All ingest endpoints respond immediately with:

{
  "ok": true,
  "eventId": "evt_01abc...",
  "correlationId": "corr_01abc..."
}

The correlationId can be used to trace the event through Rensei's audit log and Vercel runtime logs.

HMAC signature verification

Every ingest endpoint verifies the provider's HMAC signature before processing the event. Requests with missing or invalid signatures are rejected with 401 Unauthorized.

Secrets are per-app, not per-org

Webhook signing secrets are issued per application (once per provider integration), not per organization. If you configure a custom provider application (enterprise tier), your workspace-specific secret overrides the default.

Signing secrets are configured by the platform operator at the deployment level. Enterprise orgs that have configured custom provider apps have their secret resolved from a per-workspace override. Deployment-level webhook secret configuration is covered in the operator docs.

Provider setup

Linear webhook setup

Signature header: linear-signature

Linear HMAC is computed as HMAC-SHA256(payload, secret) with the result hex-encoded.

In Linear, navigate to Settings > API > Webhooks.
Click New Webhook.
Set the URL to https://app.rensei.ai/api/webhooks/ingest/linear.
Select the event types you want to ingest (at minimum: Issue, Comment, AgentActivity).
Copy the signing secret and configure it on your Rensei workspace under Settings > Integrations > Linear > Webhook Secret.

Recommended event types:

Event	Purpose
`Issue` (created, updated)	Trigger SDLC workflows on new issues
`Comment` (created)	React to `@-mentions` in issue comments
`AgentActivity`	Handle Linear AgentSession lifecycle events

# Verify your webhook is working
curl -X POST https://app.rensei.ai/api/webhooks/ingest/linear \
  -H "Content-Type: application/json" \
  -H "linear-signature: <computed-hmac>" \
  -d '{"type": "Issue", "action": "create", "data": {...}}'

GitHub webhook setup

Signature header: X-Hub-Signature-256

GitHub HMAC uses sha256=<hex-digest> format.

No manual webhook setup is required for GitHub. Installing the Rensei GitHub App subscribes the platform to events for every repository the installation can access; deliveries arrive on /api/webhook/github, verified against the App-level signing secret, and route to projects via repo-project bindings.

Events delivered include push, pull_request, pull_request_review, check_run, issues, and issue_comment.

Vercel webhook setup

Signature header: x-vercel-signature

Vercel HMAC uses the raw body and HMAC-SHA1.

In the Vercel dashboard, navigate to Settings > Webhooks.
Add a new webhook pointing to https://app.rensei.ai/api/webhooks/ingest/vercel.
Select deployment events (deployment.created, deployment.succeeded, deployment.error).
Copy the signing secret and configure it in Rensei under Settings > Integrations > Vercel > Webhook Secret.

GitHub Actions webhook setup

Path: POST /api/webhooks/ingest/github-actions

Auth: Uses the same GitHub signature verification as the main GitHub webhook.

Configure GitHub Actions to POST to this URL using the repository_dispatch event or a custom workflow step with curl:

- name: Notify Rensei of workflow completion
  run: |
    curl -X POST https://app.rensei.ai/api/webhooks/ingest/github-actions \
      -H "Content-Type: application/json" \
      -H "X-Hub-Signature-256: sha256=$(echo -n '${{ toJson(github) }}' | openssl dgst -sha256 -hmac '${{ secrets.RENSEI_WEBHOOK_SECRET }}' | cut -d' ' -f2)" \
      -d '${{ toJson(github) }}'

Processing pipeline

After signature verification and idempotency check, events flow through this pipeline asynchronously via after():

Idempotency

Each event is deduplicated by provider event ID. Re-delivered webhooks (e.g. Linear retry on 5xx) are detected and discarded - the original processing is preserved.

Response timing

The ingest endpoint aims to respond in under 100ms. All processing after idempotency check runs in after() (Next.js deferred execution), so provider webhook timeout budgets are never at risk.

Incident.io events

Incident lifecycle events use a separate path:

POST /api/webhooks/ingest/incident-io

This endpoint handles incident.created, incident.updated, incident.resolved, and incident.action_items.* events.

Debugging webhook delivery

Webhook delivery records are not stored in the webhook_deliveries table for Linear and Vercel providers - that table is GitHub-only. For non-GitHub webhook forensics, use:

Vercel runtime logs - filter by correlationId from the ingest response
Audit events - request a bounded page from GET /api/audit, then inspect returned eventType values; the list route has no server-side event-type filter

# Check recent ingest events
curl "https://app.rensei.ai/api/audit?limit=200" \
  -H "Authorization: Bearer rsk_live_..."

Linear Integration - connect Linear OAuth and AgentSession
GitHub Integration - GitHub App install and webhook routing
Vercel Integration - Vercel deployment events
Audit API - trace events through the audit log

On this page