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.
1. The sentinel internal integration
Section titled “1. The sentinel internal integration”Sentry → Settings → Developer Settings → Custom Integrations → Create New Integration → Internal Integration.
- Name:
sentinel - Webhook URL:
<FunctionUrl>sentry, the CDK stack output withsentryappended - 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_alertpayload 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.
2. Store both in SSM
Section titled “2. Store both in SSM”SENTRY_WEBHOOK_SECRET='<client secret>' \SENTRY_API_TOKEN='<auth token>' \BOT_CLIENT_SECRET='<from the Microsoft setup>' \ scripts/put-parameters.shWrites /sentinel/sentry-webhook-secret and /sentinel/sentry-api-token.
3. The automation project
Section titled “3. The automation project”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.
4. Capture the action template
Section titled “4. Capture the action template”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:
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.jsonAn 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.
5. Staged alert swap
Section titled “5. Staged alert swap”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.
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 prodAlready-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.
6. Rollback drill
Section titled “6. Rollback drill”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.
.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 stagingNotes on the workflows API
Section titled “Notes on the workflows API”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_idsandaction_filters, which is the serializer’s internal naming. SenddetectorIdsandactionFilters, 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 omittingenabledresets it totrue, silently re-enabling a disabled alert. It stays inPUT_KEYSso that cannot happen. - Workflows are org-scoped, not project-scoped. There is no project in the URL.
migrate_rules.pyresolves--projectby joining the alert’sdetectorIdsagainst/organizations/{org}/detectors/. Each project has anerrorMonitor and anissue_streamMonitor; the alerts hang offissue_stream, and the migration never changesdetectorIds.