> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macroscope.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Trigger an agent over HTTP, poll for results, or deliver them to Slack or a webhook.

## Authentication

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

```text theme={null}
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

```bash theme={null}
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**:

```json theme={null}
{
  "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

```bash theme={null}
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:

```json theme={null}
{
  "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:

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

### Response payload

Macroscope POSTs this JSON to an external destination:

```json theme={null}
{
  "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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.