How do I test Sentry issue alerts about 5xx errors on an API before a real incident?

Tares lets you test Sentry issue alerts before a real incident by posting a sample payload to the source’s ingest URL and reading the result under Recent events and Fields. Sentry reaches Tares through the webhook connector and a Sentry-side setup, because Tares has no connector of its own for Sentry today. Once the mapping looks right, you add the Sentry signing secret and let a real Sentry alert rule send the first event.

How it works

Sentry delivers issue and error alerts as webhook POSTs from an integration you create under Settings, Developer Settings. The body is JSON with a top-level action, an installation object, a data object and an actor object. The resource it concerns is named in the Sentry-Hook-Resource header.

On the Tares side this is a webhook source. Tares stores the whole payload lossless and maps the fields you declare as labels into the event envelope. Because action is a top-level field, it can serve as the event_type_field.

Sentry signs its deliveries, and the signature is the credential. You set signature_scheme to hmac_sha256, signature_header to Sentry-Hook-Signature, and signing_secret to the integration Client Secret. The source needs no Tares API key and no Bearer header. These signing options are described in the Tares release notes, not on the webhook connector page.

For a push source, test_source takes no payload and only returns the ingest endpoint, so it does not check your label mapping. To check the mapping, post a sample payload and read the result on the source page.

Set it up

1. Create the source. Ask a connected agent: “Use tares to create a webhook source for Sentry issue alerts.” The agent calls create_source and returns the ingest URL. You can also use Sources, Add source, webhook in the console. Start with the label mapping only:

- name: sentry-api-errors
  connector: webhook
  config:
    event_type_field: action
    text_template: 'Sentry {action}'
    labels:
      - { name: action, field: action, primary: true }

2. Post a sample payload to the ingest URL. Write a body shaped like a Sentry delivery, with a stand-in 5xx description in data:

curl -X POST http://localhost:8787/ingest/<ingest_key> \
  -H 'Content-Type: application/json' \
  -d '{"action": "created", "installation": {"uuid": "test"}, "data": {"title": "500 Internal Server Error on /api/orders"}}'

3. Open the source page. Under Recent events, confirm the event arrived with created as its event type and the text you expect. Under Fields, see which payload fields arrive and how often, then declare more labels for the ones you want to correlate on, such as the API service name. Keep event_type_field and text_template on top-level fields, since they read only those.

4. Add the signing options so Tares authenticates real Sentry deliveries:

    signature_scheme: hmac_sha256
    signature_header: Sentry-Hook-Signature
    signing_secret: <client-secret>

5. In Sentry, add an integration under Settings, Developer Settings and set its Webhook URL to the Tares ingest URL. Subscribe it to the resources you want, such as issues or errors, and turn on Alert Action so alert rules can use it. Copy the integration Client Secret into the signing_secret value above.

6. Point a Sentry issue alert rule for your API’s 5xx errors at the integration, trigger a test error in a non-production environment, and check Recent events again. The event now reaches Tares through Sentry itself, and your label mapping applies to it.

What you get

• Proof that the ingest URL, the event type and the text template work before any real incident.
• A Fields view that shows which Sentry payload fields arrive, so you pick labels and a primary key from real data instead of guessing.
• Authenticated deliveries. The Sentry signature is checked, so you manage no Tares API key for this source.
• Every Sentry alert stored lossless, with the nested data object intact even where only top-level fields drive the event type and text.
• Sentry events on the same footing as your other sources. Once the labels match, Tares can correlate a 5xx alert with metrics, logs and deploys from AI SRE workflows.

When something else fits

• If your 5xx alerts come from Prometheus rules routed through Alertmanager rather than from Sentry, the alertmanager connector fits better. It makes one event per alert and records firing and resolved status.
• If you only want to test an arbitrary sender or a CI system, the plain webhook connector page covers the same post-and-verify loop without any signing.

Related