Gateway

The gateway is a Bun HTTP server (Bun.serve) defined in packages/core/src/gateway/server.ts. It normalizes incoming webhooks from five sources into a unified Signal format stored in the signals table for the Forge to process.

Endpoints

Method	Path	Integration
`GET`	`/health`	Health check, returns `{ status: 'ok' }`
`POST`	`/hooks/inbound`	Generic inbound signal (HMAC-verified via `GRIND_GATEWAY_TOKEN`)
`POST`	`/hooks/telegram`	Telegram Bot API updates
`POST`	`/hooks/discord`	Discord interactions (Ed25519 signature verification)
`POST`	`/hooks/google-calendar`	Google Calendar push notifications
`POST`	`/hooks/whatsapp`	WhatsApp Cloud API (HMAC-SHA256 signature verification)

WhatsApp also handles GET /hooks/whatsapp for the webhook verification challenge.

Signature Verification

Discord

Discord uses Ed25519 signatures verified with the Web Crypto API:

const isValid = await crypto.subtle.verify("Ed25519", publicKey, signature, body);

Key is read from GRIND_DISCORD_PUBLIC_KEY. Requests failing verification return 401.

WhatsApp Cloud API

WhatsApp signs payloads with HMAC-SHA256 using the app secret:

const expectedSig = `sha256=${hmacSha256(GRIND_WHATSAPP_APP_SECRET, rawBody)}`;
const isValid = timingSafeEqual(expectedSig, xHubSignature);

Telegram does not sign individual payloads. The bot token in the webhook URL path acts as the secret.

Signal Normalization

gateway/normalize.ts converts each platform’s payload into a unified Signal:

type Signal = {
  id: string;
  source: "telegram" | "discord" | "whatsapp" | "google-calendar" | "inbound";
  type: string;
  payload: unknown;
  normalizedText?: string;
  senderId?: string;
  channelId?: string;
  timestamp: number;
};

Signals are stored to the signals table and consumed by the Forge daemon on its next tick.

Configuration

Variable	Description
`GRIND_GATEWAY_PORT`	Port to listen on (default: `5174`)
`GRIND_GATEWAY_TOKEN`	HMAC secret for `/hooks/inbound`
`GRIND_TELEGRAM_BOT_TOKEN`	Telegram bot token
`GRIND_DISCORD_PUBLIC_KEY`	Discord app public key for Ed25519
`GRIND_WHATSAPP_APP_SECRET`	WhatsApp app secret for HMAC
`GRIND_GOOGLE_CALENDAR_CHANNEL_TOKEN`	Token for calendar push verification

See Environment Reference for the complete list including webhook paths and host binding.

Adding a New Webhook Source

Add a new endpoint case in gateway/server.ts
Implement signature verification if required
Add a normalizer in gateway/normalize.ts
Handle the new signal type in forge/engine.ts

Configuration

Security

Game Mechanics

For Contributors

Project

Endpoints

Signature Verification

Discord

WhatsApp Cloud API

Telegram

Signal Normalization

Configuration

Adding a New Webhook Source

​Endpoints

​Signature Verification

​Discord

​WhatsApp Cloud API

​Telegram

​Signal Normalization

​Configuration

​Adding a New Webhook Source

Endpoints

Signature Verification

Discord

WhatsApp Cloud API

Telegram

Signal Normalization

Configuration

Adding a New Webhook Source