On this page
Wake Holon Agents on Error Alerts with Self-Hosted GlitchTip
GlitchTip is an open-source, Sentry-compatible error tracking platform (both backend and frontend repositories are MIT licensed). Holon requires no dedicated GlitchTip adapter: a project alert's generic webhook recipient posts an error summary to Holon's wake callback, and the agent uses a project API token to retrieve issue and event details.
This guide covers only this integration path. It is not an OIDC integration and does not replace client-side application SDK ingestion.
Verified Versions and Findings
Verified on 2026-11-16 in an isolated Docker Compose environment. No Holon runtime code modifications are required.
- GlitchTip container image
glitchtip/glitchtip:latest, digestsha256:c245745b4179667da3aebd73fb8d4f1fd918f7d68ba07d1fd73ea688933b6e01(built 2026-11-09). Inbound delivery requests use User-AgentGlitchTip/7.0.0. - Holon
0.59.0(33e2fcb4b). - Forward flow: After ingesting an error via
POST /api/{project_id}/store/?sentry_key=<DSN public key>, the webhook arrives within approximately one alert cycle. Holon responds toPOST /api/callbacks/wake/<token>with HTTP 200. The REST response forGET /api/0/issues/1/has atitlethat matches the webhookattachments[0].title(bothProbeError: glitchtip webhook verificationin this test).GET /api/0/issues/1/events/returns anevent_idmatching the ingestion response. - Negative cases: Missing or invalid Bearer tokens return
401 {"detail":"Unauthorized"}. Whenquantityexceeds the number of events in the time window, no webhook is dispatched and no wake occurs. An invalid recipient URL will not reach Holon.
Prerequisites
- A machine capable of running Docker. Bind GlitchTip only to localhost or a private test network; do not expose port 8080 to the public internet.
- An existing Holon
wake_hintcallback URL. This URL is a capability secret: enter it only into GlitchTip's recipient configuration; do not write it into documentation, plans, logs, or screenshots. - If the callback host is on a local, loopback, or Tailscale CGNAT address (
100.64.0.0/10), you must enableGLITCHTIP_ALLOW_PRIVATE_IPS. GlitchTip treats CGNAT ranges as non-routable private addresses; if disabled, recipient creation will be rejected or dropped by outbound SSRF protections.
Step 1: Deploy GlitchTip
The current latest image uses a single-process architecture: ./bin/start.sh serves HTTP, consumes background task queues, and initializes the database on startup. Do not split migrate or worker services as older documentation suggested; running bin/run-worker.sh in the image will be explicitly rejected.
Queue configuration uses VALKEY_URL; REDIS_URL serves as a fallback. redis:7 protocol is fully compatible. The HTTP listening port is controlled by PORT, mapped below to localhost 127.0.0.1:8080.
services:
postgres:
image: postgres:16-alpine
environment:
POSTGRES_DB: glitchtip
POSTGRES_USER: glitchtip
POSTGRES_PASSWORD: "<db-password>"
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U glitchtip -d glitchtip"]
interval: 5s
retries: 20
redis:
image: redis:7-alpine
web:
image: glitchtip/glitchtip:latest
ports:
- "127.0.0.1:8080:8080"
environment:
DATABASE_URL: "postgres://glitchtip:<db-password>@postgres:5432/glitchtip"
VALKEY_URL: "redis://redis:6379/0"
SECRET_KEY: "<random-secret-key>"
PORT: "8080"
GLITCHTIP_DOMAIN: "http://glitchtip.example.com:8080"
ENABLE_ORGANIZATION_CREATION: "true"
GLITCHTIP_ALLOW_PRIVATE_IPS: "true"
depends_on:
postgres:
condition: service_healthy
volumes:
pgdata:
GLITCHTIP_DOMAIN must be the final address accessed by users and agents. If omitted, the webhook's title_link and API permalink default to http://localhost:8000/.... Keep GLITCHTIP_ALLOW_PRIVATE_IPS=true only when the callback target resides on an internal network.
Health check: GET /_health/ returns HTTP 200.
Step 2: Create User, Project, and API Token
The current image's HEADLESS_CLIENTS setting only supports browser; there is no app token client. Registration uses the headless browser API and requires obtaining a CSRF cookie first:
GET /_allauth/browser/v1/configPOST /_allauth/browser/v1/auth/signupwith JSON{"email","password"}and headersX-CSRFTokenandReferer. When email delivery is unconfigured,ACCOUNT_EMAIL_VERIFICATIONdefaults tonone, immediately logging in and issuing asessionid.- Using the same session:
POST /api/0/organizations/{"name":"..."},POST /api/0/organizations/{org}/teams/{"slug":"..."}, andPOST /api/0/teams/{org}/{team}/projects/{"name":"...","platform":"python"}. POST /api/0/api-tokens/with session authentication, body example:{"label":"holon","scopes":["project:read","project:write","event:read","event:write","org:read"]}. The returnedtokenappears only once; treat it as a secret.GET /api/0/projects/{org}/{project}/keys/to read the DSN. Thepublicfield is a UUID; strip its hyphens to use assentry_keyduring ingestion.
Subsequent queries use Authorization: Bearer <token> without depending on the session cookie.
Step 3: Configure Alert Recipient
POST /api/0/projects/{org}/{project}/alerts/:
{
"name": "holon-error-alert",
"timespanMinutes": 60,
"quantity": 1,
"uptime": false,
"alertRecipients": [
{"recipientType": "webhook", "url": "http://<holon-host>:<port>/api/callbacks/wake/<token>"}
]
}
recipientType must be webhook (generic webhook). quantity specifies the error threshold, and timespanMinutes defines the evaluation window. Both fields must be set, or the alert will be skipped by background evaluation tasks. The default evaluation interval is ALERT_NOTIFICATION_INTERVAL seconds (defaults to 60 if unset).
Step 4: Ingest a Test Error
curl -sS -X POST "http://127.0.0.1:8080/api/1/store/?sentry_key=<dsn-public-key>" -H 'Content-Type: application/json' -d '{"event_id":"<uuid>","message":"probe","level":"error","platform":"python","exception":{"values":[{"type":"ProbeError","value":"glitchtip webhook verification"}]}}'
A successful ingestion returns {"event_id":"..."}. The issue is generated asynchronously by worker tasks, and the alert is dispatched in the next evaluation cycle.
Webhook Payload and API Mapping
The generic webhook delivers a summary rather than the raw Sentry event:
{
"text": "GlitchTip Alert",
"attachments": [
{
"title": "ProbeError: glitchtip webhook verification",
"title_link": "http://glitchtip.example.com:8080/holon-test/issues/1",
"fields": [{"title": "Project", "value": "holon-probe", "short": true}]
}
]
}
Holon wake callbacks operate as wake_hint: an HTTP 200 response indicates only that the runtime accepted the wake hint; the payload is never treated as operator instruction. Once awakened, the agent queries the API directly:
GET /api/0/issues/{id}/:titlematches webhookattachments[].title, whilemetadata.type/metadata.valuematch the exception details.GET /api/0/issues/{id}/events/:event_idmatches the ingestion response, andentriescontains the full exception and message payload.
The webhook payload does not include an event_id. To verify a specific event, query events using the issue ID rather than assuming the webhook payload contains the full event.
Negative Cases and Limitations
- Missing or invalid
AuthorizationBearer token: returns401 {"detail":"Unauthorized"}. - Event count below
quantity: no webhook dispatch and no wake. In our test withquantity=5and 1 event, no secondary webhook or callback arrived in the subsequent 60-second cycle. - An invalid recipient endpoint (closed port) does not wake Holon. However, GlitchTip 7's test endpoint
POST .../alerts/{id}/test/still returnsstatus: sent, as connection failures are caught internally in_postwithout error logging. Do not rely on test endpoint status or instance logs to confirm delivery; verify against Holon's HTTP access logs (status 200) and packet capture. - If a recipient URL targets a blocked address during creation, the API rejects the request immediately. Forgetting
GLITCHTIP_ALLOW_PRIVATE_IPSfor internal callbacks causes an error at creation time rather than silent failures later.
Cleanup
docker compose down -v removes the database, projects, tokens, and recipients. Never leave callback URLs in stopped containers with retained volumes.
Out of Scope
- Other recipient types such as email, Discord, or Slack.
- De-duplication policies beyond window thresholds, and uptime monitor alerts.
- UI-based project creation. This verification was conducted entirely via HTTP APIs.
