webhook

package
v0.7.12-dev.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 26 Imported by: 0

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

View Source
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"
	// EventManagedUpdated: the organization's admins changed its managed
	// settings. The core emits none itself; the build that keeps managed
	// settings delivers it through the extension seam.
	EventManagedUpdated = "managed.updated"
)

Event types. The catalog is closed; endpoints subscribe by name.

View Source
const DeliveryTimeout = egressguard.DefaultTimeout

DeliveryTimeout bounds a single delivery attempt.

View Source
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.

View Source
const JobDeliver = "webhook.deliver"

JobDeliver is the queue job kind for one webhook delivery attempt.

View Source
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.

View Source
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

func EndpointHost(raw string) string

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

func NewHTTPClient(g Guard, tlsConfig *tls.Config) *http.Client

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

func Sign(secret, body []byte, ts time.Time) string

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

func ValidEvent(e string) bool

ValidEvent reports whether e is a known event type.

func Verify

func Verify(secret, body []byte, header string, now time.Time) error

Verify checks a signature header against the body: the timestamp must be within MaxSignatureAge of now and the v1 HMAC must match (constant-time). First-party/receiver helper — the sender only calls Sign.

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

func (d *Dispatcher) Emit(ctx context.Context, orgID uuid.UUID, eventType string, data any) error

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).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL