Webhook configuration reference

echo.labstack.com/pro v0.2.0. See the task guide for setup examples.

Required fields

• ReceiveConfig: Source, Verify and Inbox; mount its terminal middleware on a dedicated route.
• Sending store: a ReplayWindow matching how long the receiver deduplicates message IDs.
• PostgreSQL: StoreConfig namespace, caps and retention values matching those saved by Migrate.

New and NewWorker start no goroutines; Run blocks while the delivery loop runs.

webhook.ReceiveConfig

Import echo.labstack.com/pro/webhook.

webhook.ReceiveConfig · webhook/receive.go:61 · echo.labstack.com/[email protected]

ReceiveConfig configures terminal ingress middleware for one dedicated route. The zero value is invalid. The middleware retains Inbox and Verify without closing them. Keep them and their stores and keys usable while the middleware serves requests. Both callbacks and their dependencies must support concurrent calls. The adapter sets the connection's read deadline to Timeout through http.ResponseController. If the response writer cannot set deadlines, your server must limit body reads to Timeout or less. Cancelling a context cannot interrupt a blocked body read. Logs contain only the source, status and a fixed reason code.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Inbox	Acceptor	Inbox is required, caller-owned and must be concurrency safe and honor ctx.	Inbox is required, caller-owned and must be concurrency safe and honor ctx.	webhook/receive.go:64
Source	string	Source is the required registered source name, 1–64 printable ASCII bytes. It must equal every Verify result's Source.	Source is the required registered source name, 1–64 printable ASCII bytes.	webhook/receive.go:67
Verify	VerifyFunc	Verify is required, retained and must be concurrency safe and honor ctx.	Verify is required, retained and must be concurrency safe and honor ctx.	webhook/receive.go:70
MaxBodyBytes	int64	MaxBodyBytes defaults to 256 KiB; valid range 1 byte–1 MiB.	MaxBodyBytes defaults to 256 KiB; valid range 1 byte–1 MiB.	webhook/receive.go:72
Timeout	time.Duration	Timeout bounds body reads, verification and acceptance from adapter entry; zero uses 5s, valid range 1–8s. See ReceiveConfig for body-read deadline requirements.	Timeout bounds body reads, verification and acceptance from adapter entry; zero uses 5s, valid range 1–8s.	webhook/receive.go:76
Logger	*slog.Logger	Logger is optional and caller-owned; nil is silent.	Logger is optional and caller-owned; nil is silent.	webhook/receive.go:78

Functions from package source

Type	Source
func (c ReceiveConfig) ToMiddleware() (echo.MiddlewareFunc, error)	webhook/receive.go:94

webhook.StandardVerifierConfig

Import echo.labstack.com/pro/webhook.

webhook.StandardVerifierConfig · webhook/http.go:285 · echo.labstack.com/[email protected]

StandardVerifierConfig configures HMAC Standard Webhooks verification for one trusted route. The zero value is invalid. Unverified headers and payloads cannot select tenant, account, type or format. For dynamic mappings, wrap VerifyFunc and parse only after verification succeeds.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Secrets	[]string	Secrets uses Endpoint's whsec_ form and bounds; any matching key verifies. Secrets is required; configure 1–8 verification secrets.	Secrets is required; configure 1–8 verification secrets.	webhook/http.go:288
Tenant	string	Source, Type and Format are required. They name the source, event type and payload format assigned to every verified message. Tenant and Account bind the route to trusted application values and may be empty.	Source, Type and Format are required. Tenant and Account bind the route to trusted application values and may be empty.	webhook/http.go:292
Source	string	Source, Type and Format are required. They name the source, event type and payload format assigned to every verified message. Tenant and Account bind the route to trusted application values and may be empty.	Source, Type and Format are required. Tenant and Account bind the route to trusted application values and may be empty.	webhook/http.go:292
Account	string	Source, Type and Format are required. They name the source, event type and payload format assigned to every verified message. Tenant and Account bind the route to trusted application values and may be empty.	Source, Type and Format are required. Tenant and Account bind the route to trusted application values and may be empty.	webhook/http.go:292
Type	string	Source, Type and Format are required. They name the source, event type and payload format assigned to every verified message. Tenant and Account bind the route to trusted application values and may be empty.	Source, Type and Format are required. Tenant and Account bind the route to trusted application values and may be empty.	webhook/http.go:292
Format	string	Source, Type and Format are required. They name the source, event type and payload format assigned to every verified message. Tenant and Account bind the route to trusted application values and may be empty.	Source, Type and Format are required. Tenant and Account bind the route to trusted application values and may be empty.	webhook/http.go:292
Tolerance	time.Duration	Tolerance defaults to 5m; valid range 1s–5m, on either side of Now. Timestamp checking limits replay age; the inbox must deduplicate IDs.	Tolerance defaults to 5m; valid range 1s–5m, on either side of Now.	webhook/http.go:295
Now	func() time.Time	Now defaults to time.Now; a supplied clock must be concurrency safe.	Now defaults to time.Now; a supplied clock must be concurrency safe.	webhook/http.go:297

webhook.HTTPSenderConfig

Import echo.labstack.com/pro/webhook.

webhook.HTTPSenderConfig · webhook/http.go:42 · echo.labstack.com/[email protected]

HTTPSenderConfig configures an opt-in Standard Webhooks sender. The zero value is invalid. Construction copies endpoints and decodes keys privately. The cloned transport uses HTTP/1 without persistent connections, compression, redirects, cookies or automatic retries.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Endpoints	map[string]Endpoint	Endpoints registers 1–64 destinations, keyed by Delivery.Destination. Keep these keys in sync with the store Routing destinations. Endpoints is required; configure 1–64 destinations.	Endpoints is required; configure 1–64 destinations.	webhook/http.go:46
Client	*http.Client	Client is optional and caller-owned. Construction copies its settings and clones its transport. Transport must be nil or *http.Transport. Neither may be mutated during construction; neither is modified. A zero Timeout selects 15s. A positive Timeout is preserved.	Client is optional and caller-owned. Transport must be nil or *http.Transport. A zero Timeout selects 15s.	webhook/http.go:51
Now	func() time.Time	Now defaults to time.Now; a supplied clock must be concurrency safe.	Now defaults to time.Now; a supplied clock must be concurrency safe.	webhook/http.go:53
Logger	*slog.Logger	Logger is optional, caller-owned and defaults to silence. Logs contain only outcome and machine code, never endpoint or delivery IDs.	Logger is optional, caller-owned and defaults to silence.	webhook/http.go:56

webhook.Endpoint

Import echo.labstack.com/pro/webhook.

webhook.Endpoint · webhook/http.go:31 · echo.labstack.com/[email protected]

Endpoint is a Standard Webhooks HMAC destination. URL must be absolute HTTPS; HTTP is permitted only for localhost or a literal loopback IP. Userinfo and fragments are refused. Secrets contains 1–8 whsec_-prefixed, standard base64 encoded keys, each decoding to 24–64 bytes. Generate keys with crypto/rand; use different keys for different endpoints. All keys sign during rotation.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
URL	string	URL is required and has no default.	URL is required and has no default.	webhook/http.go:33
Secrets	[]string	Secrets is required; configure 1–8 signing secrets.	Secrets is required; configure 1–8 signing secrets.	webhook/http.go:35

webhookpg.StoreConfig

Import echo.labstack.com/pro/webhook/webhookpg.

webhookpg.StoreConfig · webhook/webhookpg/store.go:124 · echo.labstack.com/[email protected]

StoreConfig selects storage and policy. Use keyed literals: fields may be added. Namespace, caps and retention are persisted by Migrate and must match in New. An earlier caller deadline or cancellation still ends an operation first. New and Migrate validate both timeout settings. An out-of-range value prevents either call from succeeding. New uses Timeout as its deadline. Migrate uses MigrateTimeout. Migrate neither validates nor uses Routing; New, the Store and its Workers use it.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Schema	string	Schema defaults to public (1–63 UTF-8 bytes without NUL); Namespace defaults to "default" (1–64 printable ASCII bytes).	Schema defaults to public (1–63 UTF-8 bytes without NUL); Namespace defaults to "default" (1–64 printable ASCII bytes).	webhook/webhookpg/store.go:127
Namespace	string	Schema defaults to public (1–63 UTF-8 bytes without NUL); Namespace defaults to "default" (1–64 printable ASCII bytes).	Schema defaults to public (1–63 UTF-8 bytes without NUL); Namespace defaults to "default" (1–64 printable ASCII bytes).	webhook/webhookpg/store.go:127
Timeout	time.Duration	Timeout bounds New and each Store operation; defaults to 5s, valid range 1–30s.	Timeout bounds New and each Store operation; defaults to 5s, valid range 1–30s.	webhook/webhookpg/store.go:130
MigrateTimeout	time.Duration	MigrateTimeout bounds the whole migration in place of Timeout; defaults to 1m, valid range 1s–1h.	MigrateTimeout bounds the whole migration in place of Timeout; defaults to 1m, valid range 1s–1h.	webhook/webhookpg/store.go:133
MaxMessages	int64	MaxMessages defaults to 100,000; valid range 1–10,000,000.	MaxMessages defaults to 100,000; valid range 1–10,000,000.	webhook/webhookpg/store.go:135
MaxBytes	int64	MaxBytes defaults to 512 MiB; valid range 1 MiB–1 TiB.	MaxBytes defaults to 512 MiB; valid range 1 MiB–1 TiB.	webhook/webhookpg/store.go:137
PayloadRetention	time.Duration	PayloadRetention defaults to 7 days; must be positive and at most DedupeRetention.	PayloadRetention defaults to 7 days; must be positive and at most DedupeRetention.	webhook/webhookpg/store.go:140
DedupeRetention	time.Duration	DedupeRetention defaults to 30 days; valid range 30–365 days.	DedupeRetention defaults to 30 days; valid range 30–365 days.	webhook/webhookpg/store.go:142
Routing	RoutingConfig	Routing is validated and copied by New; Migrate ignores it. The zero value registers no routes and uses RoutingConfig retry defaults in New.	The zero value registers no routes and uses RoutingConfig retry defaults in New.	webhook/webhookpg/store.go:145

Functions from package source

Type	Source
func New(ctx context.Context, pool *pgxpool.Pool, cfg StoreConfig) (*Store, error)	webhook/webhookpg/store.go:470

webhookpg.RoutingConfig

Import echo.labstack.com/pro/webhook/webhookpg.

webhookpg.RoutingConfig · webhook/webhookpg/store.go:94 · echo.labstack.com/[email protected]

RoutingConfig is StoreConfig.Routing: the registered routes and the retry policy frozen into new records. Sources maps a source name to its processor; Destinations maps a destination name to its registration. Retries back off from 1s to at most 5m with equal jitter. The Worker logs only fixed messages with direction, route, outcome, code and error-class fields.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Sources	map[string]ProcessFunc	Sources is copied; nil registers none. At most 64 named processors are accepted; callbacks are retained for the Store's lifetime and must be concurrency safe.	Sources is copied; nil registers none.	webhook/webhookpg/store.go:98
Destinations	map[string]DestinationConfig	Destinations is copied; nil registers none. At most 64 named destinations are accepted. Names in both maps are 1–64 printable ASCII bytes.	Destinations is copied; nil registers none.	webhook/webhookpg/store.go:102
MaxAttempts	int	MaxAttempts defaults to 8 per cycle; valid range 1–32. At most 32 attempts are permitted in total.	MaxAttempts defaults to 8 per cycle; valid range 1–32.	webhook/webhookpg/store.go:105
MaxAge	time.Duration	MaxAge defaults to 72h per cycle; valid range 1m–7 days.	MaxAge defaults to 72h per cycle; valid range 1m–7 days.	webhook/webhookpg/store.go:107
ProcessTimeout	time.Duration	ProcessTimeout defaults to 5s; valid range 1–15s.	ProcessTimeout defaults to 5s; valid range 1–15s.	webhook/webhookpg/store.go:109
Logger	*slog.Logger	Logger is retained for the Store's lifetime and caller-owned; nil is silent. It must be concurrency safe.	Logger is retained for the Store's lifetime and caller-owned; nil is silent.	webhook/webhookpg/store.go:112

webhookpg.DestinationConfig

Import echo.labstack.com/pro/webhook/webhookpg.

webhookpg.DestinationConfig · webhook/webhookpg/store.go:73 · echo.labstack.com/[email protected]

DestinationConfig registers one outgoing destination.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Version	string	Version is required, immutable and 1–64 printable ASCII bytes. It defines the payload and routing rules and must equal every enqueued message's Version.	Version is required, immutable and 1–64 printable ASCII bytes.	webhook/webhookpg/store.go:77
Send	webhook.SendFunc	Send is required, retained and must be concurrency safe and honor ctx.	Send is required, retained and must be concurrency safe and honor ctx.	webhook/webhookpg/store.go:80
ReplayWindow	time.Duration	ReplayWindow is the receiver's documented deduplication horizon; required, greater than RequestTimeout + 5m and at most 30 days.	ReplayWindow is the receiver's documented deduplication horizon; required, greater than RequestTimeout + 5m and at most 30 days.	webhook/webhookpg/store.go:83
RequestTimeout	time.Duration	RequestTimeout defaults to 15s; valid range 1–30s, stored to millisecond precision.	RequestTimeout defaults to 15s; valid range 1–30s, stored to millisecond precision.	webhook/webhookpg/store.go:86

webhookpg.WorkerConfig

Import echo.labstack.com/pro/webhook/webhookpg.

webhookpg.WorkerConfig · webhook/webhookpg/worker.go:45 · echo.labstack.com/[email protected]

WorkerConfig configures one Worker and bounds its Run; the zero value selects every default. Routing, callbacks, retry policy and the logger come from the Store's StoreConfig.Routing. A claim never exceeds the free slots. Idle and failed polls back off with equal jitter up to max(PollInterval, 5s) and reset on work.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Concurrency	int	Concurrency fixes the worker count and caps claimed or in-flight records; defaults to 16, valid range 1–64.	Concurrency fixes the worker count and caps claimed or in-flight records; defaults to 16, valid range 1–64.	webhook/webhookpg/worker.go:48
BatchSize	int	BatchSize caps one claim; defaults to min(8, Concurrency), valid range 1–min(16, Concurrency).	BatchSize caps one claim; defaults to min(8, Concurrency), valid range 1–min(16, Concurrency).	webhook/webhookpg/worker.go:51
PollInterval	time.Duration	PollInterval is the base idle wait; defaults to 250ms, valid range 50ms–5s.	PollInterval is the base idle wait; defaults to 250ms, valid range 50ms–5s.	webhook/webhookpg/worker.go:54
ShutdownTimeout	time.Duration	ShutdownTimeout bounds the drain after cancellation; defaults to 30s, valid range 1–60s. See Worker.Run for shutdown behavior.	ShutdownTimeout bounds the drain after cancellation; defaults to 30s, valid range 1–60s.	webhook/webhookpg/worker.go:57

Functions from package source

Type	Source
func NewWorker(s *Store, cfg WorkerConfig) (*Worker, error)	webhook/webhookpg/worker.go:108

webhookadmin.Config

Import echo.labstack.com/pro/webhook/webhookadmin.

webhookadmin.Config · webhook/webhookadmin/panel.go:39 · echo.labstack.com/[email protected]

Config selects one caller-owned store. The zero ID is "webhook"; Store has no default, so the zero Config is invalid.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
ID	string	ID is the panel ID: 1–32 bytes of [a-z0-9-] starting with a letter, not "api" or "assets". It defaults to "webhook". Use a distinct ID for each namespace. Change the ID or console Keys when switching that location to another namespace. Cursors bind the panel ID rather than the store.	It defaults to "webhook".	webhook/webhookadmin/panel.go:44
Store	*webhookpg.Store	Store is an already constructed, caller-owned store from webhookpg.New on the runtime-role pool. The panel never migrates, closes or reconfigures it. Keep the store and its pool open while any console using the panel serves requests. Required.	Required.	webhook/webhookadmin/panel.go:51
EnableReplay	bool	EnableReplay explicitly enables audited replay, unknown-outcome decisions and payload reveal. The default panel exposes reads only. Mounting an enabled panel requires console Keys and an Audit sink (or the explicit AllowUnauditedWrites opt-out).	The default panel exposes reads only. Mounting an enabled panel requires console Keys and an Audit sink (or the explicit AllowUnauditedWrites opt-out).	webhook/webhookadmin/panel.go:57

Functions from package source

Type	Source
func New(cfg Config) (*Panel, error)	webhook/webhookadmin/panel.go:113

webhookmem.DestinationConfig

Import echo.labstack.com/pro/webhook/webhookmem.

webhookmem.DestinationConfig · webhook/webhookmem/store.go:27 · echo.labstack.com/[email protected]

DestinationConfig registers a versioned outgoing destination, with the same policy and defaults as webhookpg.DestinationConfig. Send is caller-owned, retained, concurrency safe and must honor cancellation. ReplayWindow is the receiver's deduplication horizon, greater than RequestTimeout + 5m and at most 30 days. RequestTimeout defaults to 15s, valid range 1–30s.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Version	string	Version is required; configure the immutable routing version.	Version is required; configure the immutable routing version.	webhook/webhookmem/store.go:29
Send	webhook.SendFunc	Send is required, retained and caller-owned.	Send is required, retained and caller-owned.	webhook/webhookmem/store.go:31
ReplayWindow	time.Duration	ReplayWindow is required and has no default.	ReplayWindow is required and has no default.	webhook/webhookmem/store.go:33
RequestTimeout	time.Duration	RequestTimeout defaults to 15s; valid range 1s–30s.	RequestTimeout defaults to 15s; valid range 1s–30s.	webhook/webhookmem/store.go:35

webhookmem.RoutingConfig

Import echo.labstack.com/pro/webhook/webhookmem.

webhookmem.RoutingConfig · webhook/webhookmem/store.go:42 · echo.labstack.com/[email protected]

RoutingConfig freezes outgoing routing and retry policy. Destinations is copied (at most 64). MaxAttempts defaults to 8, range 1–32. MaxAge defaults to 72h, range 1m–7 days. Logger is optional, caller-owned and silent when nil. Callbacks and logger must be safe for concurrent use.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Destinations	map[string]DestinationConfig	Destinations is optional; nil registers none, with at most 64 entries.	Destinations is optional; nil registers none, with at most 64 entries.	webhook/webhookmem/store.go:44
MaxAttempts	int	MaxAttempts defaults to 8; valid range 1–32 attempts per cycle.	MaxAttempts defaults to 8; valid range 1–32 attempts per cycle.	webhook/webhookmem/store.go:46
MaxAge	time.Duration	MaxAge defaults to 72h; valid range 1m–7 days per cycle.	MaxAge defaults to 72h; valid range 1m–7 days per cycle.	webhook/webhookmem/store.go:48
Logger	*slog.Logger	Logger is optional and caller-owned. Nil logs nothing.	Logger is optional and caller-owned. Nil logs nothing.	webhook/webhookmem/store.go:50

webhookmem.StoreConfig

Import echo.labstack.com/pro/webhook/webhookmem.

webhookmem.StoreConfig · webhook/webhookmem/store.go:59 · echo.labstack.com/[email protected]

StoreConfig bounds live records plus terminal records inside their duplicate window. Namespace defaults to "default"; each Store is independent. MaxMessages defaults to 1,000 (range 1–100,000); MaxBytes defaults to 16 MiB (range 1 KiB–1 GiB). Logical bytes charge payload and all outgoing strings plus 512 bytes per record, not Go heap usage. Terminal records expire at first intent plus ReplayWindow (enqueue time plus ReplayWindow if never sent). Store operations reclaim expired terminal records; live records are never evicted.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Namespace	string	Namespace defaults to default. Each memory store is independent.	Namespace defaults to default.	webhook/webhookmem/store.go:61
MaxMessages	int64	MaxMessages defaults to 1000; valid range 1–100000.	MaxMessages defaults to 1000; valid range 1–100000.	webhook/webhookmem/store.go:63
MaxBytes	int64	MaxBytes defaults to 16 MiB; valid range 1 KiB–1 GiB. This counts logical bytes, not heap usage.	MaxBytes defaults to 16 MiB; valid range 1 KiB–1 GiB.	webhook/webhookmem/store.go:66
Routing	RoutingConfig	Routing at zero registers no destinations and uses the RoutingConfig retry defaults.	Routing at zero registers no destinations and uses the RoutingConfig retry defaults.	webhook/webhookmem/store.go:68

Functions from package source

Type	Source
func New(cfg StoreConfig) (*Store, error)	webhook/webhookmem/store.go:104

webhookmem.WorkerConfig

Import echo.labstack.com/pro/webhook/webhookmem.

webhookmem.WorkerConfig · webhook/webhookmem/worker.go:19 · echo.labstack.com/[email protected]

WorkerConfig bounds Run. Concurrency defaults to 16 (1–64); PollInterval defaults to 250ms (50ms–5s); ShutdownTimeout defaults to 30s (1–60s). Unlike webhookpg there is no batch acquisition or idle polling backoff.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Concurrency	int	Concurrency defaults to 16; valid range 1–64.	Concurrency defaults to 16; valid range 1–64.	webhook/webhookmem/worker.go:21
PollInterval	time.Duration	PollInterval defaults to 250ms; valid range 50ms–5s.	PollInterval defaults to 250ms; valid range 50ms–5s.	webhook/webhookmem/worker.go:23
ShutdownTimeout	time.Duration	ShutdownTimeout defaults to 30s; valid range 1s–60s.	ShutdownTimeout defaults to 30s; valid range 1s–60s.	webhook/webhookmem/worker.go:25

Functions from package source

Type	Source
func NewWorker(s *Store, cfg WorkerConfig) (*Worker, error)	webhook/webhookmem/worker.go:39

Delivery and storage limits

Setting	Default or limit
Endpoint.Secrets	whsec_ plus standard base64 of 24–64 random bytes
Endpoint.Secrets / StandardVerifierConfig.Secrets	At most eight
StandardVerifierConfig.Tolerance	Five minutes; range one second–five minutes; checks past and future skew
Standard Webhooks headers	ID 128 bytes; timestamp 20 bytes; signature 4096 bytes
ReceiveConfig.MaxBodyBytes	256 KiB by default; at most 1 MiB
ReceiveConfig.Timeout	Five seconds by default; covers body read, verification and acceptance
HTTPSenderConfig.Client.Timeout	15 seconds by default
HTTPSenderConfig response body	Reads and discards at most 4 KiB
Sender response header bytes	At most 16 KiB
webhookpg.StoreConfig.MaxMessages	100,000 by default
webhookpg.StoreConfig.MaxBytes	512 MiB by default
webhookpg.StoreConfig.PayloadRetention	Seven days by default
webhookpg.StoreConfig.DedupeRetention	30 days by default
RoutingConfig.MaxAttempts	Eight by default
RoutingConfig.MaxAge	72 hours by default
Message attempt count	At most 32
StoreConfig.Routing.Destinations[name].ReplayWindow	Required; greater than RequestTimeout + 5m; at most 30 days

Set ReplayWindow on the sending store to the remote receiver’s documented deduplication period. Keep the receiver’s deduplication records for at least that long.

Wait for Run and in-flight requests before closing stores and pools.

Related pages

Package explanation · Task guide · Problem catalog