# PostHog

> Connect PostHog so insight alerts open incidents, Ace measures who is affected, and Ace can roll a feature flag out in stages or switch it off after approval.

Source: https://tryace.dev/docs/integrations/posthog

Ace reads PostHog to measure product impact during an incident, finding which events changed, how many users are affected and which feature flags are involved. Insight alerts can open incidents, and Ace can roll a flag out or switch it off as a kill switch.

| | |
| --- | --- |
| Category | Product |
| Ace reads | Event volumes and trends, distinct users, feature flags, exceptions, annotations |
| Ace can change | Feature flag rollout percentage and on/off state, only after an admin allows actions |
| Opens incidents | Yes, from insight alerts, for workloads that route PostHog |
| Setup | Settings form, plus a webhook destination on a PostHog insight alert |

## What Ace reads

Ace reads one PostHog project while it investigates a workload that lists PostHog under **Investigation sources** or routes its alerts.

- Events whose volume changed most in the incident window, compared with an equal window before it.
- 15-minute counts and distinct users for one event.
- Flags that match a search, with their active state and rollout percentage.
- Exceptions in the window, grouped by error tracking issue, with type, message, event count and affected users.
- Your team's annotations around the incident.
- The incident's failure event after a fix, to confirm the problem stopped.

Ace also adds the connected project to the System Map.

## What Ace can change

Ace proposes PostHog actions only after an admin turns on **Allow Ace to run approved actions** for the connection. Each one needs approval by default, and earned autonomy can let either one run under an Automatic policy for a workload and environment you confirm. See [Actions and approvals](https://tryace.dev/docs/concepts/actions-and-approvals).

| Action | What it does | Approval | Undo |
| --- | --- | --- | --- |
| Flag rollout | Rolls a flag out in stages, for example 10%, 50%, then 100%. It changes the rollout percentage of one release condition only. You set the wait between stages (60 to 3,600 seconds). | Approval, or Automatic under your policy | Yes. Restores the previous rollout. |
| Flag switch | Turns a flag off as a kill switch, or turns it on. | Approval, or Automatic under your policy | Yes. Restores the previous state. |

Ace applies these safeguards:

- Ace writes with the flag version it saw at approval, so PostHog refuses the change if anyone edited the flag since.
- PostHog also refuses a switch when the flag needs a PostHog approval or other active flags depend on it.
- Ace rechecks the incident between stages.

These actions need the `feature_flag:write` scope, and Settings shows whether the key has it.

## What opens an incident

PostHog alerts open incidents only on workloads that route this connection (**Integration alerts** on, PostHog selected). Ace accepts insight alerts sent to a webhook destination and drops alerts that no workload routes.

- An `$insight_alert_firing` event opens or joins an incident at high severity. Each alert is its own group, so repeated firings of one alert join one incident.
- An alert that reports "not firing", "resolved" or "ok" resolves it.
- Ace ignores other events, and it accepts a custom body only if the body names an alert ID.

Ace doesn't poll PostHog, so without the webhook PostHog alerts don't reach Ace.

## Before you start

- The **admin** role in Ace.
- A PostHog insight with an alert, or permission to create one.
- Your **Project ID**, under **Settings** > **General** in **Project token & ID**.

## Credentials and permissions

Limit the key to this one project. Don't use the **Read-only access** preset, which grants far more than Ace needs.

| Credential | Where to create it | Scopes | Why Ace needs it |
| --- | --- | --- | --- |
| Personal API key (needed) | **Settings** > **Personal API keys** | Read on Project, Query, Feature flag and Annotation (`project:read`, `query:read`, `feature_flag:read`, `annotation:read`) | Read the project, run queries, and read flags and annotations. |
| Same key (only for actions) | Same | Write on Feature flag (`feature_flag:write`) | Roll flags out and switch them on or off. |
| Token (only for alerts) | Generated by Ace | None | Proves that alert deliveries come from your PostHog webhook destination. |

## Set up

### 1. Create a personal API key in PostHog

1. Open **Settings** > **Personal API keys** and choose **Create personal API key**.
2. Label it Ace and set **Expiration**, for example 90 days.
3. Under **Organization & project access**, choose **Projects** and select only this project.
4. Leave **Select preset** alone. Under **Scopes**, set Read on Project, Query, Feature flag and Annotation. Set Write on Feature flag only if Ace should roll out or switch flags.
5. Create the key and copy it.

### 2. Connect PostHog in Ace

1. Open **Settings** > **Data sources** and choose **PostHog**.
2. Fill in the form:

   | Field | What to enter |
   | --- | --- |
   | **Personal API key** | The key you created. |
   | **PostHog URL** | Optional. Leave blank for `https://us.posthog.com`. Use `https://eu.posthog.com` for the EU cloud, or your own host. |
   | **Project ID** | The numeric project ID. |

3. Select **Connect PostHog**. Before it saves, Ace checks that the key can read the project, run a query and read feature flags.

A self-hosted **PostHog URL** must use HTTPS and be reachable from the public internet, because Ace doesn't connect to private or internal network addresses.

### 3. Send alerts to Ace

1. In the **Alerts** section, copy the webhook URL.
2. Select **Generate token** and copy the token, which Ace shows only once.
3. In PostHog, open the insight to watch, open **Alerts**, create an alert and add a **Webhook** destination.
4. Paste the URL and keep the default JSON body. Under **Secret headers**, add `Authorization` with the value `Bearer`, a space and the token.

### 4. Route alerts to a workload

Open the workload in Ace, turn on **Integration alerts**, and select PostHog as a source.

### 5. Optional: allow actions

Turn on **Allow Ace to run approved actions**. To let flag actions earn Automatic, confirm their workload and environment on the same panel.

## Confirm it's working

- If the host is wrong for your region, the connection's checks suggest the US or EU host.
- The **Alerts** badge shows **Not set up**, **Waiting for first event**, **Verified** or **Last delivery failed**. Trigger the alert or send a test from PostHog, and the badge turns **Verified** when the first delivery with the right token arrives.
- A failed delivery shows the reason, such as a bearer token that doesn't match.
- To rotate the token, select **Generate a new token** and update the PostHog secret header.

## Disconnect

1. In Ace, open the PostHog connection under **Settings** > **Data sources** and select **Disconnect**. To stop actions and keep the connection, turn off **Allow Ace to run approved actions** instead.
2. In PostHog, remove the webhook destination from your alerts and delete the Ace personal API key. Ace creates nothing in PostHog.

## Next steps

- [LaunchDarkly](https://tryace.dev/docs/integrations/launchdarkly)
- [Actions and approvals](https://tryace.dev/docs/concepts/actions-and-approvals)
- [All integrations](https://tryace.dev/docs/integrations)