Recipe: Send bundles to a webhook

Bundles already land in /var/lib/sentry-v2/bundles. To get them into chat, a ticket queue or your own service, point a webhook at it. Every request is signed, so the receiver can tell it came from your host.

1. Make a key

# install -m 0600 -o root -g root /dev/null /etc/sentry-v2/webhook.key
# openssl rand -hex 32 > /etc/sentry-v2/webhook.key

The daemon refuses a key file that's group- or world-readable, not owned by root, or empty.

If you'd rather systemd hand the key over, keep it outside /etc/sentry-v2 and use a credential. Add a drop-in:

# /etc/systemd/system/sentry-v2.service.d/credentials.conf
[Service]
LoadCredential=webhook-hmac:/etc/sentry-v2/webhook.key

and use the credential's name, webhook-hmac, as hmac_key_file below. Run systemctl daemon-reload after adding the drop-in.

2. Point the sink at your endpoint

In /etc/sentry-v2/sentry-v2.toml:

[sinks.webhook]
url = "https://hooks.example.com/sentry-v2"
hmac_key_file = "/etc/sentry-v2/webhook.key"

It has to be HTTPS. If your endpoint uses an internal CA, add ca_file = "/etc/pki/tls/certs/internal-ca.pem".

# systemctl reload sentry-v2

A bad key or URL makes the reload fail, and the old configuration stays live. Check sentry-v2ctl status for the error.

3. Check the signature on the other end

Each request carries X-Sentry-V2-Timestamp and X-Sentry-V2-Signature: sha256=<hex>, an HMAC-SHA256 of <timestamp>.<body>. Sinks has a ten-line Python check and an openssl one-liner. Compare in constant time and reject old timestamps, or a captured request can be replayed.

If the endpoint is down

Every bundle is spooled to disk first and sent oldest-first, so nothing is lost while your endpoint is away. A transient failure is retried with backoff for up to an hour. A 400, 413, 415 or 422 means the receiver rejected that bundle, so it's dropped with a warning instead of blocking the rest.

To rotate the key, replace the file and systemctl reload sentry-v2.