webhook

Webhook Verification Middleware

What it does

Verifies webhook signatures using configured secrets, timestamp checks, and optional replay protection.

How to implement

package main

import (
	"github.com/oarkflow/fh"
	"github.com/oarkflow/fh/mw/webhook"
)

func main() {
	app := fh.New()
	app.Use(webhook.New(webhook.Config{
		SecretFunc: func(c fh.Ctx) ([]byte, error) {
			return []byte("secret"), nil
		},
	}))

	app.Get("/", func(c fh.Ctx) error {
		return c.Status(fh.StatusOK).SendString("ok")
	})
}

Impact

Protects inbound webhooks from spoofing and replay. Adds HMAC/hash cost per request.

Ordering guidance

Run after body limit and before webhook handlers. Pair with replay store and idempotency.

Production considerations

Use provider-specific signature formats where needed. Rotate secrets safely and record failed verification attempts.

Replay protection

Replay protection is on by default: Config.Replay falls back to a process-local kv.Store if unset, so a captured (signature, timestamp) pair cannot be resent within Tolerance. For multi-instance deployments behind a load balancer, supply a shared kv.Store (e.g. Redis-backed) so replay detection works across instances.

For a single-instance deployment that needs replay markers to survive a restart, construct kv.NewFileStore(dir, kv.WithFileGCInterval(gcInterval)) and pass it as Config.Replay. Storage failures reject rather than silently allow a replay.