Sending Deploy Events to Better Stack

Better Stack does not have a native deploy-marker or release-annotation API. Instead, the recommended way to surface DeployHQ deployments inside Better Stack is to send a structured log line to a Telemetry source on every deploy, then chart or alert on it from your existing dashboards.

This guide walks through:

1. Creating a Better Stack source to receive the events.
2. Adding an HTTP integration in DeployHQ that posts to that source.
3. (Optional) Charting deploys on a Better Stack dashboard.

Why a log line and not a heartbeat?

Better Stack heartbeats are designed to expect periodic pings. Sending a one-off ping on each deploy will cause Better Stack to fire missing-heartbeat incidents in between deploys, which is not what you want. The Telemetry logs ingest endpoint is the right tool: it accepts arbitrary JSON, indexes it for search, and is chartable from a dashboard.

1. Create a Better Stack source

In Better Stack, go to Telemetry > Sources and add a new source. Choose HTTP API as the source type.

After creating the source, open its settings page and copy two values:

• The ingest hostname (shown as $INGESTING_HOST in Better Stack code samples), e.g. s1234567.eu-nbg-2.betterstackdata.com.
• The source token.

Better Stack authenticates with a Bearer token: Authorization: Bearer <SOURCE_TOKEN>.

2. Add an HTTP integration in DeployHQ

In your project, click Integrations in the left-hand menu, then New Integration. Pick HTTP (not HTTP Post — that one is the legacy form-encoded variant).

Fill in:

• URL: https://YOUR_INGESTING_HOST (the hostname you copied from the Better Stack source settings).
• Authentication method: None (the token goes in a custom header).
• Custom headers:
  • Authorization: Bearer YOUR_SOURCE_TOKEN
  • Content-Type: application/json
• Payload: Choose Custom and paste a JSON template such as:

{
  "message": "Deployment of %project% to %servers%",
  "level": "info",
  "deployhq": {
    "project": "%project%",
    "servers": "%servers%",
    "branch": "%branch%",
    "revision": "%endrev%",
    "deployer": "%deployer%",
    "status": "%status%",
    "url": "%deploymenturl%"
  }
}

The placeholders above are the standard DeployHQ template variables: %project%, %servers% (comma-joined list of server names), %branch%, %endrev% (the revision being deployed to), %deployer%, %status%, and %deploymenturl%. Other variables such as %commitrange%, %started_at%, %completed_at%, and %deployment_overview% are also available — use the ones that fit your dashboard needs.

Choose when to trigger the integration (typically on successful deployments only) and select the servers it should fire for, then click Create Integration.

3. Verify the events are arriving

Trigger a deployment, then in Better Stack open Telemetry > Live tail on the new source. You should see a JSON log line with your deployhq payload appear within a few seconds.

If nothing arrives, check the deployment's Notifications log in DeployHQ for HTTP errors. The most common issues are:

• A typo in the source token, which returns 401 Unauthorized.
• Sending to the wrong region's ingest URL (Better Stack has region-specific endpoints; check your source settings).
• A 403 from a proxy in front of Better Stack — see Troubleshooting HTTP Request 403 Errors.

4. (Optional) Chart deploys on a dashboard

In Better Stack, create a dashboard chart that filters for deployhq.status = "Successful" and groups by deployhq.project. You can plot a count over time to see deploy frequency, or use the events as overlay markers on a latency or error-rate chart by filtering the same source.

What this integration does not do

• It does not create a native "Deploy" object in Better Stack — there is no such concept in their product today. The events live as searchable log lines.
• It does not annotate Better Stack monitors or status pages directly. If you need that, you would post to a separate webhook on your status page tooling.

If you would like a first-class Better Stack deploy integration, let us know — we track demand and revisit the build decision when there is a clear customer need.