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:

```json
{
  "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](Article: #686).

## 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.