Sentry to nova-admin (errors webhook)

This wires a Sentry org at nova-admin's webhook receiver. Each issue / event_alert event Sentry sends becomes a Block Kit card posted to #nova-errors by the Sentry Errors Router flow.

Overview

When Sentry detects a new error it POSTs a signed JSON payload to the receiver at webhookReceiver/sentry-errors. The receiver verifies the signature, persists the raw event under webhook-events, and dispatches every flow whose trigger source is this webhook slug. The Sentry Errors Router flow runs in script mode, formats the event as a Block Kit card, and posts it to #nova-errors. No LLM in the hot path.

Prerequisites

• Nova admin role on a connected Sentry org (pooriaarab).
• The errors agent + Sentry Errors Router flow + sentry-errors webhook are already provisioned in production by packages/cli/src/scripts/seed-errors-agent.ts. Re-run that script if any of the three docs are missing.
• #nova-errors channel exists and @nova is a member.

Webhook URL + secret

https://us-central1-nova-admin.cloudfunctions.net/webhookReceiver/sentry-errors

The signing secret lives on the webhook doc in Firestore at webhooks/{id}.secret and is never committed. Retrieve or rotate it with one of:

• The webhook_get MCP tool (shipped in PR #2511) — @nova webhook_get sentry-errors.
• Direct Firestore query against webhooks where slug == "sentry-errors".

Sentry signs each request with HMAC-SHA256 hex over the raw body and sends the digest in the sentry-hook-signature header. The receiver compares it byte-for-byte against the stored secret.

Step-by-step in Sentry

Option A — Internal Integration (recommended)

This is the path with signature verification.

1. Sentry → Settings → Custom Integrations → Create New Integration → Internal Integration.
2. Name: Nova Admin Errors. Webhook URL: paste the URL above.
3. Webhook Secret: paste the secret from webhooks/{id}.secret.
4. Under the Webhooks tab, subscribe to:

issue
event_alert

Optionally also metric_alert if you want metric breaches to hit the same channel. 5. Permissions: minimal — Read on Issue & Event is enough. The receiver doesn't write back into Sentry. 6. Save and install on the org. Sentry will start signing requests with the secret you pasted; the matching sentry-hook-signature header is what the receiver verifies.

Option B — Alert Rule webhook (per-project)

Simpler, but skips signature verification — the receiver will accept any POST that hits the slug.

• Sentry → Project → Alerts → New Issue Alert → action "Send a notification via a custom webhook" → URL: paste the URL above.

Use this only for a one-off project test; Option A is the production path.

Verifying it works

1. In Sentry → Custom Integrations → "Nova Admin Errors", click Test Webhook.
2. In Firestore, watch webhook-events for new docs with slug: "sentry-errors".
3. In Firestore, watch flow-runs for a run with flowId == <Sentry Errors Router id> reaching status: "completed".
4. A test card should appear in #nova-errors. If it doesn't, open the run doc — errors[] or the slack_message node-run's output will say why.

Troubleshooting

• Signature verification fails (401): the secret in Sentry doesn't match webhooks/{id}.secret. Re-fetch via webhook_get and re-paste. The receiver does an exact-string HMAC-SHA256 hex comparison; trailing whitespace on either side will fail.
• Events arrive but no Slack post: the router flow isn't wired to the webhook. Check that webhooks/{id}.flowIds includes the router flow id. The flow_create auto-wire path (PR #2536) handles this for flows created via the API; manually-edited flows need the field set by hand.
• Bot not posting in #nova-errors: run /invite @nova in the channel. The Slack post will surface as a node-run error with channel_not_found or not_in_channel otherwise.
• No webhook event docs at all: check the Cloud Function logs for webhookReceiver — most likely Sentry is hitting a stale URL or the integration was never installed on the org.

Future (V2)

Sentry events will gain: severity scoring (P0 / P1 / P2 / P3), repro steps, screen recording attachment, and an auto-draft PR + Linear ticket. Tracked separately.