Webhook gateway

An optional Go service that accepts provider webhooks, verifies them and queues them, taking that work off PHP. It is optional and the application is complete without it. Without the gateway, webhooks go to the Laravel route exactly as they always have. Deploy it when webhook volume becomes a bottleneck, not because it exists.

What it does

provider ──▶ gateway ──▶ Redis queue ──▶ Horizon ──▶ flow execution
                │
                └──▶ application ingress   (anything it cannot decide itself)

Per delivery: rate-limit by channel, read the routing entry from Redis, verify the signature, claim an idempotency key, publish the job. About a millisecond, no PHP process involved. The second arrow matters more than the first. Redis is a cache for the gateway, never the source of truth. On a cache miss, an unreadable Redis, an unknown platform or a spec it cannot execute, it forwards the request to the application, which resolves the channel from its database and repopulates the cache. A cold or broken Redis costs throughput, not deliveries.

How verification works without platform code

The gateway knows nothing about Telegram. Each channel adapter publishes an ingress spec — a small declaration of how that platform’s webhook is signed and deduplicated:

{
  "v": 1,
  "scheme": "header_equals",
  "parameter": "x-telegram-bot-api-secret-token",
  "prefix": "",
  "idempotency": "tg:{channel}:{body.update_id}"
}

Adding a channel therefore stays a pure PHP change and needs no gateway release. A platform whose verification is too complex to express declaratively simply does not publish a spec, and its webhooks stay on the PHP path. Both implementations are held to contracts/ingress/golden.json — 40 cases executed by both the PHP and the Go test suites, so the two cannot drift apart.

Building from source

The gateway is a single static binary with no runtime dependencies: a build on any machine runs on any Linux of the same architecture — no matching libc, no interpreter, nothing to install alongside it. Prerequisites: Go 1.27 or newer. Nothing else; the only dependency is the Redis client, vendored through go.mod.

cd gateway
make build

That produces bin/gateway, with the version stamped in from git describe so a running process can be traced back to a commit.

Target	Does
`make build`	Build for the host platform
`make dist`	Cross-compile for `linux/amd64`, `linux/arm64`, `darwin/arm64`
`make test`	Run the suite with the race detector
`make lint`	Check `gofmt` formatting and run `go vet`
`make check`	`lint` then `test`
`make all`	`check` then `build`
`make install-local`	Install the binary into `/usr/local/bin`
`make clean`	Remove `bin/`

Go needs no per-target toolchain, so make dist produces every supported platform’s release binary from one developer machine.

Run make check before shipping a gateway build. Its spec executor is held to the same golden file as the PHP implementation, so a regression here is a regression in webhook verification for every channel.

As a container image

docker build -t fapost-gateway:local --build-arg VERSION=$(git describe --tags --always) gateway/

The build is two-stage and the final stage is scratch: the shipped image holds the binary, root certificates, and nothing else — no Go toolchain, no shell, no package manager. That keeps it small and leaves an attacker who reaches the most exposed process in the stack with no tools to work with. The image runs as UID 65534 and carries no .env; configuration is injected by the runtime, so one image is promoted unchanged from staging to production.

Installing

With Docker Compose

The gateway sits behind a profile, so it starts only when asked:

docker compose -f docker/compose.yaml --env-file .env --profile gateway up -d

Standalone

cd gateway
make build
sudo install -m 0755 bin/gateway /usr/local/bin/gateway

Then generate the supervisor files:

php artisan gateway:install

It asks how the gateway will run, where providers will deliver, and where to log, then writes the settings into .env and generates a systemd unit, a logrotate config or a compose fragment into gateway/dist/ for you to review and install. Nothing is written outside the project and no service is restarted.

Configuration

Set by gateway:install, or by hand.

Routing

Variable	Default	Meaning
`WEBHOOK_INGRESS_DRIVER`	`laravel`	`laravel` or `gateway` — where newly registered channels point
`WEBHOOK_GATEWAY_URL`	—	Public URL providers deliver to
`GATEWAY_ADDR`	`:8080`	Listen address, e.g. `127.0.0.1:8080`
`GATEWAY_UPSTREAM_URL`	`WEBHOOK_BASE_URL`	The application’s own ingress, used for the fallback
`GATEWAY_TRUSTED_PROXIES`	empty	Addresses whose `X-Forwarded-For` may be believed
`GATEWAY_QUEUE`	`flow.execution`	Queue verified deliveries are pushed onto

Limits and timeouts

Variable	Default	Meaning
`GATEWAY_RATE_PER_SECOND`	`30`	Per-channel limit; `0` disables
`GATEWAY_RATE_BURST`	`60`	Burst allowance above the sustained rate
`GATEWAY_MAX_BODY_BYTES`	`1048576`	1 MiB — well above any provider’s update payload
`GATEWAY_DEDUP_TTL`	`24h`	How long an idempotency key is remembered
`GATEWAY_SPEC_CACHE_TTL`	`30s`	How long a published ingress spec is cached
`GATEWAY_READ_TIMEOUT`	`10s`
`GATEWAY_WRITE_TIMEOUT`	`15s`
`GATEWAY_IDLE_TIMEOUT`	`60s`
`GATEWAY_SHUTDOWN_TIMEOUT`	`20s`	Drain window on `SIGTERM`
`GATEWAY_REDIS_TIMEOUT`	`2s`

Logging

Variable	Default	Meaning
`GATEWAY_LOG_LEVEL`	`info`
`GATEWAY_LOG_FORMAT`	`json`
`GATEWAY_LOG_DESTINATION`	`stdout`	`stdout` or `file`
`GATEWAY_LOG_PATH`	empty	Required when the destination is `file`

Redis

Variable	Default
`REDIS_HOST`	`127.0.0.1`
`REDIS_PORT`	`6379`
`REDIS_USERNAME`	empty
`REDIS_PASSWORD`	empty
`REDIS_DB`	`0`
`REDIS_PREFIX`	derived from `APP_NAME`

Redis settings are not duplicated: the gateway reads the same REDIS_* variables as the application. REDIS_PREFIX in particular must match, or every lookup misses and the gateway proxies everything while appearing healthy.

Migrating existing channels

Switching the driver only affects channels registered from that moment on. Existing ones keep the URL their provider stored, and both paths stay valid, so there is no cutover and no window to race against.

php artisan ops:ingress-migrate              # report what is still behind
php artisan ops:ingress-migrate --apply      # queue re-registration, in batches

Re-registration reuses the same public hash and secret — only the host changes — so the provider sees no interruption. Batching exists because setWebhook is rate-limited; re-run until the report is empty. Rolling back is the same command after setting the driver back to laravel.

Order of operations

Publish the specs — php artisan ops:ingress-specs-publish
Deploy the gateway and put TLS in front of it
Set WEBHOOK_INGRESS_DRIVER=gateway and WEBHOOK_GATEWAY_URL
Migrate existing channels at your own pace

Step 1 comes first for a reason: without published specs the gateway has nothing to verify against and proxies every delivery straight back to the application. ops:webhook-warmup republishes them too, so a single command restores all ingress state after a Redis flush.

Verifying

php artisan gateway:doctor

Checks the driver, that Redis is reachable, that the key prefix is what the gateway will resolve, that published specs match the adapters, that the gateway’s health endpoint answers, and how many channels are still on the old URL.

Operating

TLS. The gateway speaks plain HTTP; terminate in front with Traefik or Caddy. The terminator must not modify the request body — signatures cover the exact bytes the provider sent. Logs. JSON on stdout by default. In file mode, SIGHUP reopens the file, so logrotate handles rotation; the same signal also drops cached ingress specs, so a republish takes effect without a restart. Shutdown. SIGTERM drains in-flight requests. This matters more than usual: a delivery already answered with 200 will not be sent again, so cutting those requests off loses messages outright. What is never logged. The webhook hash is the credential for a channel, so only a fingerprint of it appears. Request bodies and signature headers never do.

​What it does

​How verification works without platform code

​Building from source

​As a container image

​Installing

​With Docker Compose

​Standalone

​Configuration

​Routing

​Limits and timeouts

​Logging

​Redis

​Migrating existing channels

​Order of operations

​Verifying

​Operating

​Related

What it does

How verification works without platform code

Building from source

As a container image

Installing

With Docker Compose

Standalone

Configuration

Routing

Limits and timeouts

Logging

Redis

Migrating existing channels

Order of operations

Verifying

Operating

Related