How to Wire Any Webhook to a Desk Light
A matte-black enclosure and three vertically arranged domed lenses define Status Light. A generic webhook adapter can translate service events into red, amber or green, but only after the real light's input method is documented and tested.
What does the listener actually have to do?
The public listener accepts an HTTPS request, preserves the raw body, verifies the sender's signature and checks the delivery time and unique identifier. It then validates a small set of expected fields, writes a normalized event to a queue and returns a successful response quickly.
A separate local worker consumes that event, applies a state policy and calls the hardware adapter. This split keeps slow hardware, retries and desk availability out of the internet request path. It also makes captured events easy to replay in a test environment.
How do webhooks reach a machine behind a router?
The safest common choices are a small hosted receiver that forwards normalized events through an authenticated outbound channel, or a managed tunnel configured for one narrow endpoint. Direct router port forwarding puts the laptop and listener on the public internet and adds firewall, certificate, patching and availability work.
If the signal is not time-sensitive, polling may be simpler. A local poller needs no inbound path and can ask the service for current state rather than accepting deliveries.
How do you keep the endpoint from being abused?
Use the provider's documented signature scheme, compare signatures without timing leaks and reject stale timestamps. Keep secrets outside source control, rotate them deliberately and allow only the event types, repositories and branches the light needs. Limit body size and request rate before JSON parsing.
Record delivery identifiers so retries do not repeat side effects. Do not place a reusable token in the URL, log raw secrets or execute commands supplied by payload fields.
Which services are worth wiring first?
Start with one event that already changes what you do: a production deployment failure, an important CI result or an agent permission request. Define exactly what each colour means and where detail lives. Decorative streams of low-priority events train people to ignore the signal.
The Status Light offers the visible output, not a confirmed webhook receiver. Prove the listener with a software-only indicator, simulate duplicates and invalid signatures, then add hardware through the smallest verified local interface. Store only the normalized fields needed for the signal and set a retention limit for request logs. A payload may contain repository names, author details or other private data even when the light needs only a result. Document how to disable the endpoint and revoke its secret during an incident.