Webhooks

Authentication

Create a webhook in Settings → Connections → Webhooks. Save its API key, which is shown only once, and its Trigger URL.

POST https://hooks.macroscope.com/api/v1/workspaces/{workspaceType}/{workspaceId}/query-agent-webhook-trigger

Send Content-Type: application/json and X-Webhook-Secret: <api-key>.

Trigger a query

curl --fail-with-body "$TRIGGER_URL" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: $WEBHOOK_SECRET" \
  -d '{"query":"Summarize changes to payments this week."}'

Field	Type	Requirement
`query`	string	Required. Instructions for the agent.
`timezone`	string	Optional IANA timezone, such as `America/Los_Angeles`, for date references.
`responseDestination`	object	Optional push destination. Omit to retrieve the result by polling.
`responseDestination.slackChannelId`	string	Slack channel to receive the result.
`responseDestination.slackThreadTs`	string	Optional thread timestamp for a Slack reply.
`responseDestination.webhookUrl`	string	Allowlisted public HTTPS endpoint, as an alternative to Slack.

The trigger returns 202 Accepted:

{
  "jobToken": "<signed-job-token>",
  "pollUrl": "https://hooks.macroscope.com/api/v1/workspaces/{workspaceType}/{workspaceId}/query-agent-jobs",
  "workflowId": "abc-123-def-456"
}

jobToken authorizes reading this job’s result for about one hour. workflowId is deprecated. Poll using the returned URL and bearer token; do not put the token in a URL.

Polling for results

curl -i "$POLL_URL" -H "Authorization: Bearer $JOB_TOKEN"

HTTP	Body	Action
`202`	`{"status":"running"}`	Retry after the response’s `Retry-After` interval, in seconds.
`200`	`{"status":"completed","response":"..."}`	Read the result.
`200`	`{"status":"failed"}`	The job failed; do not treat HTTP 200 alone as success.

An expired token returns 403. Retriggering creates another job with a fresh token; it does not resume the old job.

Push destinations

To send results to Slack, add:

{
  "query": "Summarize changes to payments this week.",
  "responseDestination": {
    "slackChannelId": "C0123456789",
    "slackThreadTs": "1234567890.123456"
  }
}

Omit slackThreadTs for a channel message. For an external endpoint, use webhookUrl instead:

{
  "query": "Summarize changes to payments this week.",
  "responseDestination": {
    "webhookUrl": "https://example.com/macroscope-callback"
  }
}

Response payload

Macroscope POSTs this JSON to an external destination:

{
  "query": "Summarize changes to payments this week.",
  "response": "The payments service now...",
  "workflowId": "abc-123-def-456"
}

Slack destinations receive the agent’s response as a message.

URL allowlisting

A GitHub organization admin must add external destinations in Settings → Connections → Webhooks → Allowed External URLs. Destinations must be public HTTPS endpoints without embedded credentials. Private, loopback, link-local, and reserved addresses are rejected, including hostnames resolving to them at delivery time. Redirects are not followed: a 3xx is a delivery failure. Allowlist the final endpoint.

Error codes

HTTP	Trigger request	Poll request
`400`	Malformed request or missing query.	—
`401`	Missing or invalid webhook secret.	Missing or invalid job token.
`403`	Wrong workspace or disallowed destination.	Expired token or workspace mismatch.
`404`	—	Job not found.

Pricing

Code Review

Status

Integrations

Workspace

Resources

Authentication

Trigger a query

Polling for results

Push destinations

Response payload

URL allowlisting

Error codes

​Authentication

​Trigger a query

​Polling for results

​Push destinations

​Response payload

​URL allowlisting

​Error codes

Authentication

Trigger a query

Polling for results

Push destinations

Response payload

URL allowlisting

Error codes