x/messaging/webhook Primer
x/messaging/webhook Primer
Section titled “x/messaging/webhook Primer”Experimental — API compatibility is not frozen. Evaluate before adopting in production. Check Release Posture for current maturity status.
Open this page after x/messaging Primer when the change is narrowly about webhook transport: verifying inbound webhook signatures, delivering outbound webhooks with retry, or bridging a pubsub topic to HTTP callbacks.
x/messaging/webhook is a subordinate package within the x/messaging capability family. Start new app-facing messaging feature discovery in x/messaging before opening this package directly.
Start here when
Section titled “Start here when”- you are verifying inbound webhook signatures from external providers (
VerifyHMAC,VerifyGitHub,VerifyStripe) - you are setting up an inbound webhook receiver with deduplication and IP allowlisting (
in.go,inbound_dedup.go,inbound_ip_allowlist.go) - you are implementing outbound webhook delivery with retry and dead-letter queue (
out.go,outbound_retry.go,outbound_queue.go) - you are bridging a
x/messaging/pubsubtopic to HTTP webhook callbacks (bridge.go) - you are creating or configuring a webhook service (
NewService,NewMemStore)
Do not start here when
Section titled “Do not start here when”- the work is a new app-facing messaging capability — start from x/messaging Primer to confirm family placement
- the change is about business-specific webhook workflows or domain event schemas — keep that in application code
- the work is generic pub-sub fan-out without HTTP delivery — start from
x/messaging/pubsub - the change needs durable queue primitives for non-webhook task delivery — start from
x/messaging/mq
First files to read in the current repository
Section titled “First files to read in the current repository”x/messaging/webhook/module.yamlx/messaging/webhook/in.gox/messaging/webhook/out.gox/messaging/webhook/bridge.gox/messaging/webhook/inbound_hmac.gox/messaging/webhook/outbound_retry.go
Concrete ownership examples
Section titled “Concrete ownership examples”Keep it in x/messaging/webhook when the work is about | Move out when the work becomes |
|---|---|
VerifyHMAC, VerifyGitHub, VerifyStripe: HMAC signature verification, fail-closed on mismatch | business logic that runs after verification — keep that in your handler |
inbound_dedup: idempotency key extraction and deduplication for inbound events | application-level event processing or business deduplication rules |
inbound_ip_allowlist: restricting inbound webhook sources by IP | network-level firewall configuration or reverse-proxy allowlisting |
outbound_queue, outbound_retry: durable delivery with retry backoff and dead-letter capture | application-specific delivery SLAs or business retry policies |
bridge.go: connecting a x/messaging/pubsub topic to HTTP webhook callbacks | generic event routing outside the webhook delivery surface |
Why this primer exists
Section titled “Why this primer exists”Webhooks fail in security-specific ways — signature bypass, replay attacks, and IP spoofing — that make the transport layer high-risk. x/messaging/webhook centralizes the verification and delivery primitives so that each service does not reimplement HMAC checking independently. The invariant is: fail closed on verification errors and keep secrets out of logs.