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

# HTTP and webhooks

> Requests, responses, and inbound hooks.

## Send an HTTP request

`miktingHttp` uses Node.js's global `fetch` implementation. It supports GET,
POST, PUT, PATCH, DELETE, and HEAD. A body is optional. When you send one,
choose `json`, `form` (URL-encoded), or `text`. Headers and query parameters
support templating. Use `auth` for bearer or basic authentication stored in
secrets.

Requests time out after 10 seconds by default. `retries` defaults to one retry
for idempotent methods, not POST. The response size limit defaults to 1 MiB.
GET and HEAD responses can be cached with `cacheTtlSec`; the cache key includes
the method, URL, body, and a hash of Authorization. Responses with
`Set-Cookie` or `Cache-Control: no-store` or `private` are not cached. The
client sends `User-Agent: Mikting/1.0` by default.

Rate limiting is disabled by default. Configure `rateLimit.enabled`,
`maxPerMinPerGuild` (default 60), and `maxParallel` (default 5) to limit event
traffic. Requests rejected by the local limit set `mikting_ok` to false and
`mikting_error` to `rate_limited`.

## Responses and errors

`mikting_ok` means the server returned a 2xx status. It does not validate JSON
or an API-specific schema. Ordinary text responses are supported. Use an
optional `responseCheck` when an API response must satisfy a known contract.
Supported checks cover OpenAI moderation, OpenAI or Groq policy responses, and
TypeSafe Jev Noul responses. Debug checks can format a private report for the
same providers; see [Debug checks](https://mikting.docs.komo.moe/debug-checks.md).

A non-2xx response sets error variables and preserves its status, body, and
available headers. Missing secrets, local rate limits, timeouts, and network
failures set `ok` to false and use status zero when no HTTP response arrived.
Follow-up actions still run after a request fails.

Each request clears the current output namespace before it runs, including old
JSON fields, headers, validation values, and key-slot labels. It preserves
other `storeAs` namespaces. Request templates can read earlier response
values. The generic `mikting_error` remains available across the action chain;
the current namespaced error is cleared before its new request.

Bearer `auth.tokenSecret` keys can rotate through numbered slots. Rotation is
shared by provider origin and base name. Unauthorized keys are excluded, and
429 responses pause the pool according to `Retry-After`. Requests are not
replayed across keys. This helps distribute credentials but does not raise a
provider's organization quota. See [Secrets](https://mikting.docs.komo.moe/secrets.md).

## Check a JSON response

This example branches on a JSON boolean. For a strict API contract, add a
`responseCheck` and also require its `valid` output before acting:

```yaml theme={null}
actions:
  - id: miktingHttp
    args:
      method: POST
      url: 'https://api.example.com/v1/check'
      headers: { Authorization: 'Bearer {{secret.API_TOKEN}}' }
      json: { text: '%message_content%' }
      storeAs: mod
      follow-up-actions:
        - id: miktingBranch
          args:
            when: '[[mod_json_flagged]] == true'
            then:
              - id: deleteMessage
              - id: miktingReply
                args: { content: 'Flagged and logged.' }
    triggers: messageCreate
    conditions:
      - id: '!isBot'
```

## Receive a webhook

Mikting runs one `node:http` listener. `GET /health` returns a small health
response. A POST to `{hookPrefix}/:hookId` (default
`/mikting/hooks/:hookId`) emits `miktingWebhook:<hookId>` with `hook_id`,
`hook_body`, and flattened `hook_body_<path>` variables. Payloads default to a
256 KiB limit; larger requests receive 413.

Set `MIKTING_HOOK_<ID>` to require HMAC signatures for a hook. Use the hook ID
in uppercase and replace hyphens with underscores. Without a configured
secret, the hook remains open for compatibility and logs a warning. The legacy
signature is HMAC-SHA256 of the raw body in `x-mikting-sig`. The timestamped
format also sends `x-mikting-ts` and signs `<timestamp>.<raw_body>`; timestamps
must be within five minutes. Invalid signatures receive 401.

A webhook trigger can use the payload like this:

```yaml theme={null}
actions:
  - id: miktingReply
    args: { content: 'Deploy: [[hook_body_repo]] @ [[hook_body_ref]]' }
    triggers: 'miktingWebhook:deploys'
```

With `server.autoDetect` enabled, Mikting reads `SERVER_PORT`, `ALLOC_PORT`,
or `PORT`, and `SERVER_IP`. The public URL prefers `PUBLIC_DOMAIN`, then
`baseUrl`, then the configured host and port. `/mikting-status` shows the URL.
Use hard-to-guess hook IDs and configure a secret when a hook can trigger
moderation or role changes.

[Documentation home](https://mikting.docs.komo.moe/index.md) · [Source Markdown](https://gitlab.com/komomori/mikting/-/blob/main/docs/mikting-http-webhooks.md)


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