Skip to main content
To use the API, you must configure Status. To configure Status, click on Status in the left sidebar, then complete the Product Overview and Sprint Cadence. Once your backfill has finished, you’ll be able to use the API.
Macroscope exposes an inbound webhook that triggers the agent. It’s the same agent you use in Slack and GitHub, but invoked via HTTP so you can call it from CI pipelines, scripts, cron jobs, or any other system. When the agent finishes, you can get the results two ways:
  • Push — Macroscope delivers them to a destination you specify (a Slack channel or an external URL).
  • Pull — omit the destination and poll for the result using the token returned by the trigger.

​
Setup

  1. Go to Settings → Connections → Webhooks
  2. Click Add Webhook and give it a name (e.g. ci-pipeline)
  3. Copy your API key. It’s shown once and can’t be retrieved later.
  4. Copy your Trigger URL. You can access it anytime in Settings → Connections → Webhooks.
Your Trigger URL will follow this format: 
POST https://hooks.macroscope.com/api/v1/workspaces/{workspaceType}/{workspaceId}/query-agent-webhook-trigger

​
URL Allowlisting

If you want Macroscope to deliver results to an external URL (rather than Slack), that URL must be allowlisted first. For example, if you’re routing results to a Zapier or n8n webhook endpoint, add that URL here. Manage the list in Settings → Connections → Webhooks → Allowed External URLs. Only GitHub organization admins can add or remove URLs. Must be HTTPS.

​
Request

Every request needs two headers: 
-H "Content-Type: application/json"
-H "X-Webhook-Secret: your-api-key"
POST a JSON body to your trigger URL:
​
query
string
required
The question to ask the agent.
​
responseDestination
object
Where to deliver the results. Use slackChannelId (string) to post to Slack, or webhookUrl (string) to POST to an external URL (must be allowlisted). Optionally include slackThreadTs (string) to reply in a specific Slack thread.Optional. Omit it to retrieve the result by polling instead.
​
timezone
string
IANA timezone (e.g. America/Los_Angeles). Affects date references in the query.
The request returns 202 Accepted with a job token and poll URL: 
{
  "jobToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "pollUrl": "https://hooks.macroscope.com/api/v1/workspaces/{workspaceType}/{workspaceId}/query-agent-jobs",
  "workflowId": "abc-123-def-456"
}
  • jobToken — a signed token (valid ~1 hour) authorizing you to read this one job’s result. Send it as an Authorization: Bearer header when polling.
  • pollUrl — where to poll for the result. The token is not in the URL.
  • workflowId — deprecated.

​
Example Requests

Deliver results to Slack: 
curl -X POST \
  "https://hooks.macroscope.com/api/v1/workspaces/{workspaceType}/{workspaceId}/query-agent-webhook-trigger" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: your-api-key" \
  -d '{
    "query": "What were the main changes this week?",
    "responseDestination": { "slackChannelId": "C0123456789" },
    "timezone": "America/Los_Angeles"
  }'
Deliver results to a Slack thread: 
curl -X POST \
  "https://hooks.macroscope.com/api/v1/workspaces/{workspaceType}/{workspaceId}/query-agent-webhook-trigger" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: your-api-key" \
  -d '{
    "query": "Investigate this alert and respond in thread",
    "responseDestination": {
      "slackChannelId": "C0123456789",
      "slackThreadTs": "1234567890.123456"
    },
    "timezone": "America/Los_Angeles"
  }'
Deliver results to an external URL: 
curl -X POST \
  "https://hooks.macroscope.com/api/v1/workspaces/{workspaceType}/{workspaceId}/query-agent-webhook-trigger" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: your-api-key" \
  -d '{
    "query": "What were the main changes this week?",
    "responseDestination": { "webhookUrl": "https://your-endpoint.com/callback" },
    "timezone": "America/Los_Angeles"
  }'

​
Polling for results

If you didn’t set a responseDestination, poll the pollUrl from the trigger response. Send the jobToken as a bearer token: 
curl -i "$POLL_URL" -H "Authorization: Bearer $JOB_TOKEN"
StatusHTTPBody
Still running202{ "status": "running" }
Finished200{ "status": "completed", "response": "..." }
Failed200{ "status": "failed" }
While running, the response carries a Retry-After header (seconds) suggesting how long to wait before polling again. The job token is valid for about one hour — if it expires before the job finishes you’ll get 403; re-trigger to get a fresh one.

​
Example: trigger and poll

# 1. Trigger without a destination
RESP=$(curl -s -X POST \
  "https://hooks.macroscope.com/api/v1/workspaces/{workspaceType}/{workspaceId}/query-agent-webhook-trigger" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: your-api-key" \
  -d '{ "query": "What were the main changes this week?" }')

JOB_TOKEN=$(echo "$RESP" | jq -r .jobToken)
POLL_URL=$(echo "$RESP" | jq -r .pollUrl)

# 2. Poll until done
while :; do
  OUT=$(curl -s "$POLL_URL" -H "Authorization: Bearer $JOB_TOKEN")
  [ "$(echo "$OUT" | jq -r .status)" != "running" ] && break
  sleep 10
done
echo "$OUT" | jq -r .response

​
Response Payload

When the agent finishes, Macroscope POSTs this to your Slack channel or URL: 
{
  "query": "What were the main changes this week?",
  "response": "Here are the main changes...",
  "workflowId": "abc-123-def-456"
}

​
Error Codes

CodeMeaning
202Query accepted.
400Malformed request or missing query.
401Missing or invalid X-Webhook-Secret.
403Wrong workspace, or webhook URL not allowlisted.
When polling:
CodeMeaning
200Job finished (completed or failed).
202Still running; retry after the Retry-After interval.
401Missing or invalid job token.
403Job token expired, or doesn’t match this workspace.
404Job not found.

​
Use Cases

  • Post-deploy summaries: GitHub Actions runs a deploy, triggers a webhook asking “what changed in this release?”, and Macroscope posts a plain-English summary to your team’s Slack channel.
  • Incident response: wire a PagerDuty or Sentry alert to trigger a Macroscope webhook. The agent can investigate the error, open a PR with a proposed fix, assign the most relevant teammate as a reviewer, and post a summary to your on-call Slack channel.
  • No-code automations: a Zapier or n8n workflow triggers Macroscope every Monday morning to generate a weekly engineering digest and routes the answer to email, Notion, or wherever your team tracks updates.
  • Synchronous Q&A / chatbots: trigger a query from your own app with no destination, poll until complete, and show the answer inline — for building a custom “ask Macroscope” experience.