Documentation
¶
Overview ¶
Package webhook implements org-configurable webhooks: HMAC-SHA256 signed delivery through the async queue with 5× exponential backoff, and the SSRF egress guard (https-only, re-resolve to public unicast per attempt, block private/link-local/metadata ranges, no redirect following, 10s timeout).
Index ¶
- Constants
- func AllEvents() []string
- func EndpointHost(raw string) string
- func NewHTTPClient(g Guard, tlsConfig *tls.Config) *http.Client
- func Sign(secret, body []byte, ts time.Time) string
- func ValidEvent(e string) bool
- func Verify(secret, body []byte, header string, now time.Time) error
- type Deps
- type Dispatcher
- func (d *Dispatcher) Close() error
- func (d *Dispatcher) Deliver(ctx context.Context, endpointID uuid.UUID, eventType string, data any) error
- func (d *Dispatcher) Emit(ctx context.Context, orgID uuid.UUID, eventType string, data any) error
- func (d *Dispatcher) EmitToEndpoint(ctx context.Context, endpointID uuid.UUID, eventType string, data any) (storegen.WebhookDelivery, error)
- func (d *Dispatcher) RegisterHandlers(q queue.Client)
- func (d *Dispatcher) SetMetrics(m *metrics.Metrics)
- type ErrBlockedAddress
- type Guard
Constants ¶
const ( EventAgentCreated = "agent.created" EventVersionSubmitted = "version.submitted" EventVersionPublished = "version.published" EventVersionRejected = "version.rejected" EventVersionNeedsReview = "version.needs_review" EventVersionYanked = "version.yanked" EventAgentQuarantined = "agent.quarantined" EventAgentReinstated = "agent.reinstated" EventAdvisoryPublished = "advisory.published" // EventAgentDependencyAlert: a published version declares an MCP server // version with a newly known high/critical vulnerability. EventAgentDependencyAlert = "agent.dependency_alert" EventScanCompleted = "scan.completed" EventMemberAdded = "member.added" EventMemberRemoved = "member.removed" EventPolicyUpdated = "policy.updated" // EventRunEnded: a hosted run of one of the organization's QuickAgents // ended, in any state. The core emits none itself; the build that runs // QuickAgents In Agentry delivers it through the extension seam. EventRunEnded = "run.ended" )
Event types. The catalog is closed; endpoints subscribe by name.
const DeliveryTimeout = egressguard.DefaultTimeout
DeliveryTimeout bounds a single delivery attempt.
const EventPing = "ping"
EventPing is the event type recorded for a test delivery. It is deliberately absent from AllEvents: nobody subscribes to a ping, it is sent to one endpoint on request.
const JobDeliver = "webhook.deliver"
JobDeliver is the queue job kind for one webhook delivery attempt.
const MaxSignatureAge = 5 * time.Minute
MaxSignatureAge is the freshness window a receiver should enforce on the timestamp (±5 min). Exposed for the receiver-side Verify used in tests and by any first-party consumer.
const SignatureHeader = "X-Agentry-Signature"
SignatureHeader is the delivery signature header name.
Variables ¶
This section is empty.
Functions ¶
func AllEvents ¶
func AllEvents() []string
AllEvents lists the subscribable event types (validation, docs).
func EndpointHost ¶
EndpointHost is the scheme and host of raw, "the endpoint" when it does not parse as a URL with one. It is the only part of an endpoint's address that belongs in a log line, an audit event or a stored error: the path, the query and the user information routinely carry the endpoint's secret.
func NewHTTPClient ¶
NewHTTPClient builds a delivery client bound to the guard: no redirect following, the SSRF-checked dialer, and DeliveryTimeout unless the guard names its own. tlsConfig is nil in production (system roots); tests pass a pool trusting the httptest cert.
func Sign ¶
Sign returns the value for X-Agentry-Signature over the payload at time ts:
t=<unix>,v1=<hex(HMAC_SHA256(secret, "<unix>.<body>"))>
Binding the timestamp into the signed material (the "<t>.<body>" scheme, as used by Stripe/GitHub) stops a captured (t, signature) pair from being replayed with a fresh timestamp.
func ValidEvent ¶
ValidEvent reports whether e is a known event type.
Types ¶
type Deps ¶
type Deps struct {
Store *store.Store
Sealer *auth.Sealer
Queue queue.Client
Log *slog.Logger
// Client is the guarded delivery client; nil defaults to the strict
// production guard (NewHTTPClient(Guard{}, nil)).
Client *http.Client
// Now is the delivery clock; nil defaults to time.Now.
Now func() time.Time
// DeliveriesPerSecond is the per-org delivery rate (default 5).
DeliveriesPerSecond float64
}
Deps are the dispatcher's collaborators.
type Dispatcher ¶
type Dispatcher struct {
// contains filtered or unexported fields
}
Dispatcher records and delivers webhook events for an org.
func NewDispatcher ¶
func NewDispatcher(deps Deps) *Dispatcher
NewDispatcher builds a dispatcher, filling in production defaults.
func (*Dispatcher) Close ¶
func (d *Dispatcher) Close() error
Close releases the rate-limiter's collector goroutine.
func (*Dispatcher) Deliver ¶
func (d *Dispatcher) Deliver(ctx context.Context, endpointID uuid.UUID, eventType string, data any) error
Deliver records one delivery of eventType to the endpoint a caller named and enqueues its job: what Emit does for each subscribed endpoint, for one endpoint chosen by something other than its subscriptions — an extension routing an event to the destination an organization picked for it (pkg/extension.Webhooks). Whose endpoint it is, and whether it is active, is the caller's to have checked; the transport is the same from here on. Without a store or a queue there is nothing to record, which — unlike Emit's silent best effort — is an error, because a caller that named one endpoint expects the delivery to exist.
func (*Dispatcher) Emit ¶
Emit records a delivery per subscribed active endpoint and enqueues a delivery job for each. It is best-effort: a webhook failure never rolls back the state change that triggered it, so callers log and continue.
func (*Dispatcher) EmitToEndpoint ¶
func (d *Dispatcher) EmitToEndpoint(ctx context.Context, endpointID uuid.UUID, eventType string, data any) (storegen.WebhookDelivery, error)
EmitToEndpoint records and enqueues one delivery to a specific endpoint and returns the delivery row.
func (*Dispatcher) RegisterHandlers ¶
func (d *Dispatcher) RegisterHandlers(q queue.Client)
RegisterHandlers wires the delivery handler onto the queue (worker role).
func (*Dispatcher) SetMetrics ¶
func (d *Dispatcher) SetMetrics(m *metrics.Metrics)
SetMetrics wires the instrument set.
type ErrBlockedAddress ¶
type ErrBlockedAddress = egressguard.BlockedAddressError
ErrBlockedAddress is returned by the guarded dialer when a destination resolves to a non-public address. The guard itself is pkg/egressguard's; these names are its aliases, so the core's callers and an extension's share one implementation.
type Guard ¶
type Guard = egressguard.Guard
Guard is the SSRF egress policy (pkg/egressguard.Guard).