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

A legacy /api/webhook/github path exists for backward compatibility. Configure new webhooks to use /api/webhooks/ingest/github. Both paths process GitHub webhooks correctly; only the canonical path will receive new features.

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.

In your GitHub repository (or organization), navigate to Settings > Webhooks.
Click Add webhook.
Set the Payload URL to https://app.rensei.ai/api/webhooks/ingest/github.
Set Content type to application/json.
Enter a secret and save it in Rensei under Settings > Integrations > GitHub > Webhook Secret.
Select individual events or "Send me everything" (Rensei filters internally).

Recommended events: push, pull_request, pull_request_review, check_run, workflow_run

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 - GET /api/audit/events?type=webhook.ingest

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

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

On this page