Webhooks

Go to Settings → Webhooks and flip the toggle on. Set a token — this becomes the bearer token that every built-in endpoint checks. You can send it two ways:

# Standard
curl -H "Authorization: Bearer your-webhook-token" ...

# Alternative for services that can't set Authorization
curl -H "X-Golemcore-Token: your-webhook-token" ...

Custom hooks can use bearer too, or switch to HMAC-SHA256 with a per-hook secret — see Custom hooks.

Pick the endpoint by asking what the caller needs back:

Both endpoints actually run through the agent loop — the difference is not “does work happen” but what the caller gets back and when. Wake is the right choice when you have nothing to do with the answer. Agent is the right choice when the caller needs to see the answer, either through a callback URL or by waiting.

The wake endpoint takes a short text event and acknowledges it immediately. The agent loop runs in the background; the HTTP caller never sees the reply.

curl -X POST http://localhost:8080/api/hooks/wake \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-webhook-token" \
  -d '{
    "text": "Build completed successfully",
    "chatId": "webhook:ci"
  }'

{
  "status": "accepted",
  "chatId": "webhook:ci"
}

text is the only required field. chatId is optional and defaults to webhook:default. An optional metadata object is passed through to the message. The request body is sanitized and wrapped with [EXTERNAL WEBHOOK DATA] safety markers before it reaches the model.

The agent endpoint runs a full turn. The field is message, not text. By default it returns 202 Accepted with a run ID — the real reply is delivered later via callback URL, cross-channel delivery, or can be read from the dashboard.

curl -X POST http://localhost:8080/api/hooks/agent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-webhook-token" \
  -d '{
    "message": "Review deployment logs for errors",
    "model": "smart",
    "callbackUrl": "https://my-server.com/webhook-results"
  }'

{
  "status": "accepted",
  "runId": "550e8400-e29b-41d4-a716-446655440000",
  "chatId": "hook:550e8400-e29b-41d4-a716-446655440001"
}

All request fields, in one place:

Set syncResponse: true on an agent request to make the HTTP caller wait for the completed result instead of receiving a run ID. The endpoint holds the request open for up to timeoutSeconds (default 300) and returns the final answer in the same response body.

There are two sub-modes, and they behave differently:

A callbackUrl can be combined with either sub-mode. The callback payload is the raw agent text and is delivered independently — the schema contract only applies to the synchronous HTTP body.

A response schema turns a webhook into a contract: the caller declares the shape it wants back, and the bot is required to produce exactly that. This is how you make a webhook behave like a typed RPC.

Three things happen when you pass a responseJsonSchema:

1. Pre-flight check. The bot validates the schema itself as a Draft 2020-12 JSON Schema before it accepts the run. An empty {} is rejected, and a schema without syncResponse: true is rejected — a schema only makes sense on a synchronous call.
2. Schema-aware turn.The schema is rendered into the agent's system prompt so the model knows the exact output shape it must produce. The model tier for this turn follows the tier resolution rules below.
3. Validate and repair. The final agent output is parsed and validated against the schema. If it does not match, the bot makes up to 3 repair calls, feeding the validation errors back to the model each time. If all 3 repair calls still fail, the response returns 422.

curl -X POST http://localhost:8080/api/hooks/agent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-webhook-token" \
  -d '{
    "message": "Classify the customer report and write a one-line summary.",
    "syncResponse": true,
    "model": "smart",
    "responseValidationModelTier": "balanced",
    "responseJsonSchema": {
      "type": "object",
      "required": ["version", "result"],
      "additionalProperties": false,
      "properties": {
        "version": { "const": "1.0" },
        "result": {
          "type": "object",
          "required": ["category", "severity", "summary"],
          "additionalProperties": false,
          "properties": {
            "category": { "type": "string", "enum": ["bug", "question", "feature"] },
            "severity": { "type": "string", "enum": ["low", "medium", "high"] },
            "summary": { "type": "string" }
          }
        }
      }
    }
  }'

All of model, responseValidationModelTier, syncResponse, and responseJsonSchemaare first-class fields on the agent request body — each call chooses its own tier, sync mode, and schema independently of the webhook's defaults. A successful response for the request above is the validated JSON payload itself, not wrapped and not stringified:

{
  "version": "1.0",
  "result": {
    "category": "bug",
    "severity": "medium",
    "summary": "Upload fails with 500 when the file is larger than 10 MB."
  }
}

Headers on a schema-sync success: X-Golemcore-Run-Id, X-Golemcore-Chat-Id, and X-Golemcore-Schema-Repair-Attempts (number of repair calls it took, 0 if the first attempt matched).

Two fields can influence the model tier: model (normal request-level override) and responseValidationModelTier (a schema-specific override). The rule is:

1. No schema. responseValidationModelTier is ignored — it is only meaningful alongside a schema. The turn runs on model, or the normal default if model is omitted.
2. Schema, no responseValidationModelTier. The turn runs on model (or default). Repair calls also run on model; if that is unset they fall back to balanced.
3. Schema + responseValidationModelTier. responseValidationModelTier takes over both the main schema-constrained turn and the repair calls. model is superseded for this run.

Separately, the /tiercommand's per-session stickiness does not apply to the webhook channel at all. Webhook runs always start from scratch tier-wise and use only the rules above.

A custom hook is a mapping you define so an external system can send its own JSON shape — GitHub push events, Stripe charges, alert payloads — and the bot turns it into a message. Each custom hook lives at POST /api/hooks/<name>.

You create custom hooks in Settings → Webhooks. Every field on the async /agent endpoint is available on a mapping too, plus these:

Webhook traffic does not read from or write to global memory by default. The webhook configuration has a memoryPreset field that defaults to disabled, which means:

• The agent loop does not recall notes at the start of a webhook turn.
• The memory tool does not persist anything the bot tries to save during a webhook turn.

To opt in, set webhooks.memoryPreset in Settings → Webhooks to any of the known memory preset ids (coding_balanced, coding_fast, coding_deep, general_chat, research_analyst, ops_support). An individual /agent request can also pass memoryPreset in the body to override the webhook default for one call — unknown preset ids return 400.

This is on purpose: webhooks are often triggered by external, untrusted systems, and mixing their payloads into long-term memory can quickly pollute the notebook. Start with memory off; turn it on only for hooks you trust. See Memory for what the presets do.

Every error response carries the same small JSON body:

{
  "status": "error",
  "errorMessage": "Human-readable explanation"
}