VNOX-Server/docs/design/webhook-api.md
loki5512344 3e7f5b22dc
feat(server): protocol v2 with signed handshake, secure voice relay, media broadcast and channel authorization
Revoke voice access on channel delete, kick and permission change, and
acknowledge the sender's own chat messages.
2026-10-24 16:51:13 +02:00

23 lines
4.5 KiB
Markdown

# Community webhook API v1
Additive LNEx packets `0x0200..0x0206` manage channel-scoped integrations over an already authenticated encrypted session. `MANAGE_WEBHOOKS` is permission bit11. Management requires a persisted text channel in a guild, actual current membership, and the permission (or guild ownership). The operational HTTP listener never exposes management APIs.
- `WebhookCreate`: channel_id, name, direction (`incoming`/`outgoing`), provider (`generic`/`github`), endpoint for outgoing.
- `WebhookList`: channel_id; returns descriptors without secrets.
- `WebhookRotate`/`WebhookRevoke`: id; authorization is rechecked against its channel.
- `WebhookResult`: descriptor plus new secret only for create/rotate.
- `WebhookListResult`: descriptors. Descriptors include suspension state. All management requests use the additive `WebhookRequest` message; the packet identifies the operation.
Requests carry a unique request_id (up to 64 ASCII alphanumeric/hyphen characters), echoed in both success responses and dedicated `WebhookErrorResult` packet `0x0206`. Clients discard stale/unknown replies, including one-time secrets, and refresh after a timeout because a mutation may already have committed.
Only incoming delivery is public HTTP: `POST /v1/webhooks/{webhook_id}`. Generic integrations use `Authorization: Bearer <secret>` and JSON `{ "content": "..." }`; unknown identity/avatar/mention fields are rejected. Optional `Idempotency-Key` deduplicates retries. GitHub adapters verify `X-Hub-Signature-256` over raw bytes and use `X-GitHub-Delivery` for deduplication. GitHub initially supports push, pull_request, issues, release and ping summaries. Delivery body is capped64KiB, content4000characters; mass mention syntax is denied. A webhook sender has a reserved `webhook:<id>` identity, never a user-provided sender ID. Production publishing requires HTTPS proxying; bearer tokens must not appear in URLs or access logs.
Incoming generic secrets are random256-bit values stored only as SHA256 hashes. GitHub HMAC and outgoing signing keys require reversible storage and are AEAD-sealed using `VNOX_WEBHOOK_SECRET_KEY` (64hexcharacters, protected environment). Those modes are unavailable if the master key is not configured. Key rotation replaces the active secret and invalidates the old token immediately. No DM/Hub/private-account access is granted.
Outgoing hooks initially subscribe only to `message.created` in their configured channel. The message and outbox row commit together. Payload includes id, occurred_at and channel/message/sender/content fields. Oversized ordinary chat content is bounded with an explicit content_truncated flag; message IDs are bounded to 128 characters with id_truncated. Event/delivery IDs are server-generated. Signatures use `X-Vnox-Signature: sha256=<HMAC(timestamp+'.'+raw_body)>`, `X-Vnox-Timestamp` and `X-Vnox-Delivery`. Consumers validate time and deduplicate the `X-Vnox-Delivery` value. Retries are bounded; delivery is at least once, so duplicate sends remain possible after uncertain failures.
Only HTTPS public destinations are accepted. Each delivery re-resolves and validates every address, pins the request to that resolution, disables proxies and redirects, and applies request timeouts. Loopback/private/link-local/multicast/documentation/special addresses are rejected. Secrets/target query strings are not logged. Outbox capacity is bounded; a full hook is suspended for new events rather than blocking core chat, and management listing exposes the reason. Rotation explicitly resumes a suspended hook. Completed/terminal delivery rows are deleted, including their payload. The worker supports one active gateway process per database; shared-database multi-worker claiming is not supported. Incoming receipt retention is 24 hours with a hard cap of 4096 receipts per hook; retry identifiers outside this window may create a new message.
This contract adds server functionality; existing desktop clients do not yet have webhook-management UI. JSON/Protobuf mismatch elsewhere is not repaired by these packets. Community hooks are separate from Hub authentication and are not deployed to central.loki-code.dev.
Permission and membership changes apply at subsequent authorization checks; an already authorized delivery may finish while a role change is in progress. Credential rotation/revocation is revalidated inside the persistence transaction. Active-hook creation and outbox capacity checks share a database transaction lock, including PostgreSQL advisory locking; PostgreSQL concurrency still requires a live integration fixture.