Synchronize both language guides, API references and examples with the implemented authorization, storage and delivery behavior. Document migration requirements and accepted operational limits.
8.7 KiB
API Overview
WebHooker exposes an HTTP API via Nitro on Cloudflare Workers.
Base URL
https://your-worker.workers.dev
Endpoints
| Method | Path | Auth | Description |
|---|---|---|---|
GET |
/health |
None | Health check |
POST |
/webhook |
HMAC signature | GitHub / Gitea / custom webhook ingestion (provider auto-detected) |
POST |
/webhook/:groupId |
Per-group secret | Per-group webhook ingress (only that group's routes fire) |
POST |
/discord/interactions |
Ed25519 signature | Discord interactions (slash commands, buttons, modals) |
POST |
/telegram/webhook |
Secret token | Telegram updates (bot /gh commands) |
POST |
/feishu/webhook |
Feishu signature | Feishu events (bot /gh commands, card buttons) |
GET |
/api/richheader |
None | Open Graph page for the Telegram avatar link-preview card |
GET |
/auth/github |
None | Start GitHub OAuth flow |
GET |
/auth/github/callback |
None | OAuth callback |
POST |
/auth/github/link |
Link nonce | Confirm a bot account link (from the confirmation page) |
GET |
/auth/github/install |
Admin session | Post-install choice page: bind the installation to a group |
POST |
/auth/github/install/bind |
Admin session | Provision the chosen installation binding |
DELETE |
/auth/token/:userId |
Admin session | Revoke user token |
POST |
/api/comment |
Bearer token | Create issue comment |
POST |
/api/merge |
Bearer token | Merge pull request |
POST |
/api/close |
Bearer token | Close pull request |
POST |
/api/react |
Bearer token | Add reaction to issue |
GET |
/admin |
Admin session | Config console UI |
GET |
/admin/login |
None | Start admin sign-in (GitHub OAuth) |
GET |
/admin/logout |
Admin session | Sign out and destroy the session |
GET |
/admin/invite |
Admin session | Accept a group invite (browser page, ?token=…) |
The /admin/api/* endpoints (routes, groups, members, invites, webhook secrets, send logs, audit log) are documented separately in the Admin API.
Admin Console
See Configuration → Web UI for setup, and the Admin API reference for all management endpoints. Admin endpoints require a session cookie obtained via GET /admin/login (GitHub OAuth); the signed-in user must be listed in ADMIN_USER_IDS or manage a group. For local development only, exact DEBUG_MODE=true bypasses authentication and grants full access; never deploy with it enabled.
Health Check
GET /health
Response:
{
"status": "ok"
}
Webhook Ingestion
POST /webhook
Accepts GitHub webhook payloads. Requires valid X-Hub-Signature-256 header.
Headers:
| Header | Required | Description |
|---|---|---|
X-Hub-Signature-256 |
Yes | HMAC-SHA256 signature |
X-GitHub-Event |
Yes | Event type name |
X-GitHub-Delivery |
No | Unique delivery ID (used for dedup when present) |
Request Body: GitHub webhook JSON payload (max 1MB).
Response:
{
"ok": true,
"requestId": "…"
}
requestId is the correlation id written to the worker's logs. With inline dispatch (no queue), an event whose targets failed permanently is still answered 200, with "failed": true added.
When X-GitHub-Delivery is present and the same delivery was already accepted, the worker responds 200 { "ok": true, "duplicate": true } without re-dispatching; while the first copy is still being processed, a redelivery gets 503 so the sender retries later.
Error Responses:
| Status | Body | Cause |
|---|---|---|
401 |
{"error": "Invalid signature"} |
Signature verification failed |
400 |
{"error": "Invalid event"} |
Missing event header or malformed body |
413 |
{"error": "Request too large"} |
Body exceeds 1MB limit |
503 |
{"error": …} |
Not accepted yet — the queue rejected the event, a target failed transiently (inline dispatch), the same delivery is still being processed, or storage failed; the sender should redeliver |
Per-Group Webhook (POST /webhook/:groupId)
Verifies the payload against the group's secret (stored with the group in D1, generated from the console — Webhook endpoint panel) instead of the global secrets, and dispatches only into that group's routes. Works for GitHub (X-Hub-Signature-256), Gitea (X-Gitea-Signature) and custom (X-WebHooker-Signature) senders. Returns 404 when the group does not exist or has no secret configured, and 503 when the group's stored configuration cannot be read.
Custom Webhooks
Any JSON object signed with X-WebHooker-Signature: sha256=<hex> (HMAC-SHA256 of the raw body, group or global secret) becomes a custom event. Route it with a route whose filter is event: custom. Optional X-WebHooker-Timestamp + X-WebHooker-Nonce headers enable replay protection (signature over {timestamp}.{nonce}.{body}, ±5 min window, nonce dedup). Payload schema: see Configuration → Custom webhooks.
GitHub App Installation Events
installation webhook events (created, ...) are auto-provisioned as a fallback: a group named after the installing account (inst-{installationId}, bound via installationId) is created automatically, or existing groups whose owners match the installing account are bound to the installation. See Configuration → GitHub App tenant isolation.
The primary flow is the App's Setup URL — set it to {BASE_URL}/auth/github/install. After a user installs the App, the browser lands on:
| Method | Path | Description |
|---|---|---|
GET |
/auth/github/install |
Choice page: bind the installation to a new group or an existing group the signed-in user owns |
POST |
/auth/github/install/bind |
Provisions the binding (owner role re-checked) and redirects to /admin?install=ok |
Error Format
Error responses of the webhook, admin, OAuth and action endpoints follow the format below; the bot callbacks (/discord/interactions, /telegram/webhook, /feishu/webhook) answer errors with a plain-text body:
{
"error": "Description of the error"
}