Skip to content

Sentry setup

Two things get created by hand in Sentry: the internal integration that webhooks alerts to the receiver, and the project the receiver reports its own errors to. Everything after that is scripted.

Sentry → Settings → Developer Settings → Custom Integrations → Create New Integration → Internal Integration.

  • Name: sentinel
  • Webhook URL: <FunctionUrl>sentry, the CDK stack output with sentry appended
  • Alert Rule Action: enabled. This is what makes the integration appear as a pickable action inside issue alert rules.
  • Permissions: Issue & Event: Read. Delivery itself needs no scope; the read scope is what lets the receiver resolve an issue’s short id from the numeric id in the webhook body, which the event_alert payload does not carry.
  • Webhooks: no resource subscriptions needed. Alert-rule deliveries are driven by the rules themselves, not by a subscription.
  • Small Icon: upload docs/brand/assets/perch/perch-sentry-256.png. Cosmetic, and only shown in UI components. Sentry accepts black and transparent pixels only, which is what that file is for. See the brand asset README.

Save, then record two values:

  • the Client Secret. Sentry signs every delivery with sentry-hook-signature, an HMAC-SHA256 of the raw body under this secret.
  • the Token (auth token), used for the issue short-id lookup.
Terminal window
SENTRY_WEBHOOK_SECRET='<client secret>' \
SENTRY_API_TOKEN='<auth token>' \
BOT_CLIENT_SECRET='<from the Microsoft setup>' \
scripts/put-parameters.sh

Writes /sentinel/sentry-webhook-secret and /sentinel/sentry-api-token.

Sentry → Projects → Create Project.

  • Platform: Python
  • Name: automation
  • Team: whichever team should own it

Then Settings → Alerts → configure the default issue alert to notify by email only.

Copy the project’s DSN into config/receiver.yaml under observability.automation_dsn, then redeploy so the Lambda picks it up.

The migration script writes the sentinel action into each alert, and the exact JSON Sentry stores for that action is captured rather than assumed.

A note on names and ids first. Sentry’s UI and docs call these Monitors and Alerts; the API paths call them detectors and workflows. They are the same objects: a Monitor decides when an issue is created, an Alert decides who gets notified. The UI serves alerts from /monitors/alerts/<id>/, and those ids are the workflow ids this API uses, so an id copied from the address bar is usable here.

Add the “Send a notification via sentinel” action to one alert in the UI, then read the template straight off it and remove the hand-added action afterwards:

Terminal window
curl -sS -H "Authorization: Bearer $SENTRY_ACCESS_TOKEN" \
https://sentry.io/api/0/organizations/<your-org>/workflows/ \
| python3 -c "import sys,json; wfs=json.load(sys.stdin); acts=[a for w in wfs for af in w['actionFilters'] for a in af['actions'] if a['type']=='webhook']; a=dict(acts[0]); a.pop('id', None); print(json.dumps(a, indent=2))" \
> fixtures/sentry-workflow-action.json

An internal integration with no alert-rule UI schema registers as a plain webhook action keyed by the integration’s service slug, which is why the selector above matches on type rather than on a name.

Sentry mints that slug from the integration’s name at creation and never changes it, so a deployment that renamed its integration keeps the original slug while a fresh setup gets a sentinel-* one. scripts/migrate_rules.py reads the slug from the live integration rather than assuming either value.

Commit that file. Every later apply reads its template from it, so no service slug is ever typed by hand.

Start with the quietest slice and widen only after a real alert renders correctly. Dry run each slice first: it exercises the whole read and plan path, writes nothing, and prints exactly what would change.

Terminal window
export SENTRY_ACCESS_TOKEN='<an org admin token>'
.venv/bin/python -m scripts.migrate_rules --org acme-tools apply --project checkout --environment staging --dry-run
.venv/bin/python -m scripts.migrate_rules --org acme-tools apply --project checkout --environment staging
# soak: wait for an organic alert, or force one, and check the channel
.venv/bin/python -m scripts.migrate_rules --org acme-tools apply --project checkout --environment prod

Already-migrated alerts are reported as skipped rather than aborting the slice, so re-running a project is safe.

Each apply prints the backup path it wrote first. Keep those files; they are the rollback artifact. The filename carries the project, the environment slice, and a UTC timestamp (rule-backup-checkout-prod-2026-08-13T221500Z.json), so the passes above never overwrite each other. apply refuses to start if the backup path already exists, and refuses to touch a single live alert until every alert in the slice has planned successfully.

Run this once, deliberately, on the first swapped slice, so rollback is proven rather than assumed. rollback takes no --project: a workflow id is unique across the organization, and the backup carries it.

Terminal window
.venv/bin/python -m scripts.migrate_rules --org acme-tools rollback \
--backup fixtures/rule-backup-checkout-staging-<timestamp>.json
# confirm the stock grey card returns, then re-apply
.venv/bin/python -m scripts.migrate_rules --org acme-tools apply --project checkout --environment staging

The legacy /projects/{org}/{project}/rules/ endpoints are gone and return HTTP 410. There is no backwards-compatible replacement and no exemption. Everything above goes through /organizations/{org}/workflows/, documented at https://docs.sentry.io/api/monitors/.

Three things about that API are worth knowing before editing the script, all established by probing a disposable workflow:

  • The wire format is camelCase. The docs list body parameters as detector_ids and action_filters, which is the serializer’s internal naming. Send detectorIds and actionFilters, matching what GET returns.
  • PUT is a partial update, except for enabled. Omitted keys are left alone, so a narrow payload will not unbind an alert from its Monitor. But omitting enabled resets it to true, silently re-enabling a disabled alert. It stays in PUT_KEYS so that cannot happen.
  • Workflows are org-scoped, not project-scoped. There is no project in the URL. migrate_rules.py resolves --project by joining the alert’s detectorIds against /organizations/{org}/detectors/. Each project has an error Monitor and an issue_stream Monitor; the alerts hang off issue_stream, and the migration never changes detectorIds.