Documentation
¶
Index ¶
- Constants
- Variables
- func BuildScheduleOptions(instance triggerrepo.TriggerInstance, schedule string, taskQueue string, ...) client.ScheduleOptions
- func CancelTriggerWakeWorkflow(ctx context.Context, temporalEnv *tenv.Environment, instanceID uuid.UUID) error
- func DeleteTriggerCronWorkflowSchedule(ctx context.Context, temporalEnv *tenv.Environment, instanceID uuid.UUID) error
- func ExecuteTriggerDispatchWorkflow(ctx context.Context, temporalEnv *tenv.Environment, ...) error
- func ExecuteTriggerWakeWorkflow(ctx context.Context, temporalEnv *tenv.Environment, instanceID uuid.UUID, ...) error
- func ScheduleTriggerCronWorkflow(ctx context.Context, temporalEnv *tenv.Environment, ...) error
- func SlackAppHomeView(dashboardURL string) map[string]any
- func TriggerWakeWorkflowID(id uuid.UUID) string
- func ValidateTargetKind(targetKind string) error
- func ValidateWakeFireAt(fireAt, now time.Time) error
- func WakeConfigFields(configJSON []byte) (string, string)
- type App
- func (a *App) CancelAssistantWakes(ctx context.Context, projectID, assistantID uuid.UUID) error
- func (a *App) CancelWakeInstance(ctx context.Context, projectID uuid.UUID, instanceID uuid.UUID, ...) (triggerrepo.TriggerInstance, error)
- func (a *App) Create(ctx context.Context, params CreateParams, hooks ...InstanceDBHook) (triggerrepo.TriggerInstance, error)
- func (a *App) CreateWakeInstance(ctx context.Context, params CreateWakeInstanceParams, hooks ...InstanceDBHook) (triggerrepo.TriggerInstance, error)
- func (a *App) Delete(ctx context.Context, projectID uuid.UUID, id uuid.UUID, ...) error
- func (a *App) Dispatch(ctx context.Context, input Task) error
- func (a *App) GetInstance(ctx context.Context, projectID uuid.UUID, id uuid.UUID) (triggerrepo.TriggerInstance, error)
- func (a *App) IngestDirect(ctx context.Context, instanceID uuid.UUID, payload []byte, ...) (*Task, error)
- func (a *App) ListActiveAssistantWakes(ctx context.Context, projectID uuid.UUID, assistantID uuid.UUID) ([]triggerrepo.TriggerInstance, error)
- func (a *App) ListDefinitions() []Definition
- func (a *App) ListInstances(ctx context.Context, projectID uuid.UUID) ([]triggerrepo.TriggerInstance, error)
- func (a *App) MarkInstanceFired(ctx context.Context, instanceID string) error
- func (a *App) ProcessEvent(ctx context.Context, instance triggerrepo.TriggerInstance, ...) (*Task, error)
- func (a *App) ProcessScheduled(ctx context.Context, input ProcessScheduledInput) (*Task, error)
- func (a *App) ProcessSpeakeasySlack(ctx context.Context, instance triggerrepo.TriggerInstance, body []byte, ...) (*WebhookIngressResult, error)
- func (a *App) ProcessWebhook(ctx context.Context, instanceID uuid.UUID, body []byte, headers http.Header) (*WebhookIngressResult, error)
- func (a *App) RegisterDispatcher(dispatcher Dispatcher)
- func (a *App) RouteSlackThreadToAssistant(ctx context.Context, thread AssistantThread, channelID, threadTS string) error
- func (a *App) SetAssistantThreadRouteState(ctx context.Context, thread AssistantThread, state ThreadRouteState) error
- func (a *App) SetSpeakeasySlackTokens(tokens SpeakeasySlackTokens)
- func (a *App) SetStatus(ctx context.Context, projectID uuid.UUID, id uuid.UUID, status string, ...) (triggerrepo.TriggerInstance, error)
- func (a *App) Update(ctx context.Context, params UpdateParams, hooks ...InstanceDBHook) (triggerrepo.TriggerInstance, error)
- func (a *App) WebhookURL(instance triggerrepo.TriggerInstance) *string
- type AssistantIdentityLifecycle
- type AssistantThread
- type Config
- type CreateParams
- type CreateWakeInstanceParams
- type Definition
- type DeliveryLogger
- type DeliveryStatus
- type Dispatcher
- type EnvRequirement
- type EnvironmentLoader
- type EventEnvelope
- type HMACScheme
- type InstanceDBHook
- type Kind
- type NoopDispatcher
- type ProcessScheduledInput
- type RoutedConfig
- type RoutingFacts
- type RoutingPolicy
- type ScheduleTriggerCronWorkflowOptions
- type ScheduleWorkflowInput
- type SlackEventSummary
- type SpeakeasySlackTokens
- type Task
- type ThreadBackfill
- type ThreadRouteState
- type TriggerCronWorkflowInput
- type TriggerDeliveryLog
- type TriggerDispatchWorkflowInput
- type UpdateParams
- type WebhookIngest
- type WebhookIngressResult
- type WebhookResponse
- type WebhookVendor
Constants ¶
const ( TargetKindAssistant = "assistant" TargetKindNoop = "noop" StatusActive = "active" StatusPaused = "paused" StatusFired = "fired" StatusCancelled = "cancelled" DefinitionSlugSlack = "slack" DefinitionSlugMSTeams = "msteams" DefinitionSlugLinear = "linear" DefinitionSlugGithub = "github" DefinitionSlugCron = "cron" DefinitionSlugWake = "wake" DefinitionSlugDashboard = "dashboard" // DefinitionSlugSpeakeasySlack routes mentions and direct messages sent to // the Speakeasy Slack app to a project's managed assistant. Its instances // are system-managed and have no environment: the bot token comes from the // organization's Slack workspace connection. DefinitionSlugSpeakeasySlack = "speakeasy_slack" )
const MaxWakeHorizon = 30 * 24 * time.Hour
MaxWakeHorizon caps how far in the future a wake trigger may be scheduled.
Variables ¶
var ( ErrBadRequest = errors.New("trigger bad request") ErrAuthFailed = errors.New("trigger webhook authentication failed") )
var ErrSpeakeasySlackUnrouted = errors.New("speakeasy slack event is not routed")
ErrSpeakeasySlackUnrouted means a Slack event has no project to go to.
var SlackSignature = HMACScheme{ NewHash: func(key []byte) hash.Hash { return hmac.New(sha256.New, key) }, Header: "X-Slack-Signature", Encoding: "hex", Prefix: "v0=", Template: "v0:{timestamp}:{body}", TimestampHeader: "X-Slack-Request-Timestamp", TimestampSkew: 5 * time.Minute, }
SlackSignature is how Slack signs requests: v0=HMAC-SHA256 over "v0:{timestamp}:{body}", with timestamps more than 5 minutes off rejected.
var SpeakeasySlackConfig = []byte(`{"routing":"mentions"}`)
SpeakeasySlackConfig is the fixed config of a speakeasy_slack instance: the assistant answers when it is mentioned and in direct messages.
Functions ¶
func BuildScheduleOptions ¶
func BuildScheduleOptions(instance triggerrepo.TriggerInstance, schedule string, taskQueue string, workflowName string) client.ScheduleOptions
func CancelTriggerWakeWorkflow ¶
func CancelTriggerWakeWorkflow(ctx context.Context, temporalEnv *tenv.Environment, instanceID uuid.UUID) error
CancelTriggerWakeWorkflow: the workflow body honours cancellation by exiting before dispatch. NotFound is swallowed so cancelling an already- fired or never-started wake is a no-op.
func ExecuteTriggerDispatchWorkflow ¶
func ExecuteTriggerDispatchWorkflow(ctx context.Context, temporalEnv *tenv.Environment, input TriggerDispatchWorkflowInput) error
func ExecuteTriggerWakeWorkflow ¶
func ExecuteTriggerWakeWorkflow(ctx context.Context, temporalEnv *tenv.Environment, instanceID uuid.UUID, fireAt time.Time) error
ExecuteTriggerWakeWorkflow is idempotent: the deterministic per-instance workflow ID makes repeated scheduling of the same wake a Temporal-level no-op (WORKFLOW_ID_REUSE_POLICY_REJECT_DUPLICATE).
func ScheduleTriggerCronWorkflow ¶
func ScheduleTriggerCronWorkflow(ctx context.Context, temporalEnv *tenv.Environment, opts ScheduleTriggerCronWorkflowOptions) error
func SlackAppHomeView ¶
SlackAppHomeView builds the Home tab: a welcome message and a button linking to the Speakeasy dashboard.
func TriggerWakeWorkflowID ¶
func ValidateTargetKind ¶
func ValidateWakeFireAt ¶
ValidateWakeFireAt enforces the create-time bounds on a wake's fire_at. Pure helper so callers can test bounds without round-tripping a DB.
func WakeConfigFields ¶
WakeConfigFields decodes a wake trigger instance's config_json blob and returns the (correlation_id, fire_at) pair used by audit log call sites. Returns empty strings on decode failure so callers can still record audit events without taking down the workflow.
Types ¶
type App ¶
type App struct {
// contains filtered or unexported fields
}
func NewApp ¶
func NewApp( logger *slog.Logger, db *pgxpool.Pool, temporalEnv *tenv.Environment, envLoader EnvironmentLoader, deliveryLogger DeliveryLogger, auditLogger *audit.Logger, serverURL *url.URL, siteURL *url.URL, platformHosts map[string]string, slackClient *slackclient.SlackClient, cacheImpl cache.Cache, identities AssistantIdentityLifecycle, dispatchers ...Dispatcher, ) *App
func (*App) CancelAssistantWakes ¶
CancelAssistantWakes is the cascade hook on assistant deletion: errors per instance are folded into the returned error so a partial sweep still cancels what it can.
func (*App) CancelWakeInstance ¶
func (a *App) CancelWakeInstance(ctx context.Context, projectID uuid.UUID, instanceID uuid.UUID, hooks ...InstanceDBHook) (triggerrepo.TriggerInstance, error)
CancelWakeInstance flips an active wake to 'cancelled' and cancels its pending workflow. Idempotent for already-cancelled or already-fired wakes.
func (*App) Create ¶
func (a *App) Create(ctx context.Context, params CreateParams, hooks ...InstanceDBHook) (triggerrepo.TriggerInstance, error)
func (*App) CreateWakeInstance ¶
func (a *App) CreateWakeInstance(ctx context.Context, params CreateWakeInstanceParams, hooks ...InstanceDBHook) (triggerrepo.TriggerInstance, error)
func (*App) GetInstance ¶
func (a *App) GetInstance(ctx context.Context, projectID uuid.UUID, id uuid.UUID) (triggerrepo.TriggerInstance, error)
func (*App) IngestDirect ¶
func (a *App) IngestDirect(ctx context.Context, instanceID uuid.UUID, payload []byte, receivedAt time.Time) (*Task, error)
IngestDirect handles a synchronous, app-invoked trigger event (e.g. a message from the dashboard assistant sidebar) through the same path as webhook and schedule ingress: it builds the event from the instance's direct-ingress definition, runs ProcessEvent (status/filter/target checks + delivery log), and dispatches the resulting task inline. Returns the dispatched task, or nil when the instance is paused or the event was filtered out.
func (*App) ListActiveAssistantWakes ¶
func (a *App) ListActiveAssistantWakes(ctx context.Context, projectID uuid.UUID, assistantID uuid.UUID) ([]triggerrepo.TriggerInstance, error)
func (*App) ListDefinitions ¶
func (a *App) ListDefinitions() []Definition
func (*App) ListInstances ¶
func (a *App) ListInstances(ctx context.Context, projectID uuid.UUID) ([]triggerrepo.TriggerInstance, error)
func (*App) MarkInstanceFired ¶
MarkInstanceFired transitions an active wake instance to 'fired' and records a wake:fired audit log. The UPDATE is guarded on status='active' so a cancel that won the race is preserved (the workflow returns nil; the already-cancelled row keeps its terminal state).
func (*App) ProcessEvent ¶
func (a *App) ProcessEvent(ctx context.Context, instance triggerrepo.TriggerInstance, envelope EventEnvelope) (*Task, error)
func (*App) ProcessScheduled ¶
func (*App) ProcessSpeakeasySlack ¶
func (a *App) ProcessSpeakeasySlack(ctx context.Context, instance triggerrepo.TriggerInstance, body []byte, headers http.Header, botToken string) (*WebhookIngressResult, error)
ProcessSpeakeasySlack dispatches a Slack event the Speakeasy app's endpoint has already verified and routed to instance, using botToken for the workspace's Slack calls.
func (*App) ProcessWebhook ¶
func (*App) RegisterDispatcher ¶
func (a *App) RegisterDispatcher(dispatcher Dispatcher)
func (*App) RouteSlackThreadToAssistant ¶
func (a *App) RouteSlackThreadToAssistant(ctx context.Context, thread AssistantThread, channelID, threadTS string) error
RouteSlackThreadToAssistant delivers future events on the Slack thread rooted at threadTS to an assistant thread and subscribes the assistant to it. The assistant has seen the thread up to threadTS.
func (*App) SetAssistantThreadRouteState ¶
func (a *App) SetAssistantThreadRouteState(ctx context.Context, thread AssistantThread, state ThreadRouteState) error
SetAssistantThreadRouteState subscribes or unsubscribes an assistant from the conversation behind one of its threads and from every conversation routed to that thread.
func (*App) SetSpeakeasySlackTokens ¶
func (a *App) SetSpeakeasySlackTokens(tokens SpeakeasySlackTokens)
SetSpeakeasySlackTokens wires the token source for speakeasy_slack instances.
func (*App) SetStatus ¶
func (a *App) SetStatus(ctx context.Context, projectID uuid.UUID, id uuid.UUID, status string, hooks ...InstanceDBHook) (triggerrepo.TriggerInstance, error)
func (*App) Update ¶
func (a *App) Update(ctx context.Context, params UpdateParams, hooks ...InstanceDBHook) (triggerrepo.TriggerInstance, error)
func (*App) WebhookURL ¶
func (a *App) WebhookURL(instance triggerrepo.TriggerInstance) *string
type AssistantIdentityLifecycle ¶
type AssistantIdentityLifecycle interface {
LockTarget(ctx context.Context, tx pgx.Tx, projectID uuid.UUID, targetKind, targetRef string) error
BindRootTrigger(ctx context.Context, tx pgx.Tx, projectID, triggerID uuid.UUID) error
RetargetRootTrigger(ctx context.Context, tx pgx.Tx, projectID, triggerID uuid.UUID) error
TombstoneTrigger(ctx context.Context, tx pgx.Tx, projectID, triggerID uuid.UUID) error
}
AssistantIdentityLifecycle binds root triggers to assistant workload identities inside the trigger's own transaction. Implementations must leave triggers that do not target an identity-backed assistant unchanged. LockTarget runs before an existing trigger row is locked for an update.
type AssistantThread ¶
type AssistantThread struct {
ProjectID uuid.UUID
AssistantID uuid.UUID
// ThreadID is the assistant thread. Assistant tokens that omit it leave it
// uuid.Nil, and ChatID identifies the thread instead.
ThreadID uuid.UUID
// ChatID is the thread's chat id as carried on a tool call, used when
// ThreadID is uuid.Nil.
ChatID string
}
AssistantThread identifies one conversation of an assistant trigger target.
type CreateParams ¶
type CreateWakeInstanceParams ¶
type CreateWakeInstanceParams struct {
OrganizationID string
ProjectID uuid.UUID
Name string
AssistantID uuid.UUID
TargetDisplay string
FireAt time.Time
Note *string
CorrelationID string
}
CreateWakeInstanceParams configures a one-shot self-wake for an assistant thread. CorrelationID must match the originating thread's correlation ID so the firing event lands on the same `assistant_threads` row.
type Definition ¶
type Definition struct {
Slug string
Title string
Description string
Kind Kind
ConfigSchema []byte
CompiledConfigSchema *jsonschema.Schema
EnvRequirements []EnvRequirement
EventType reflect.Type
DecodeConfig func(raw map[string]any) (Config, error)
AuthenticateWebhook func(ctx context.Context, body []byte, headers http.Header, env map[string]string, config Config) error
HandleWebhook func(body []byte, headers http.Header, config Config) (*WebhookIngressResult, error)
BuildScheduledEvent func(instance triggerrepo.TriggerInstance, config Config, firedAt time.Time) (*EventEnvelope, error)
BuildDirectEvent func(instance triggerrepo.TriggerInstance, config Config, payload []byte, receivedAt time.Time) (*EventEnvelope, error)
ExtractSchedule func(config Config) (string, error)
}
func GetDefinition ¶
func GetDefinition(slug string) (Definition, bool)
func List ¶
func List() []Definition
func NewWebhookDefinition ¶
func NewWebhookDefinition( vendor WebhookVendor, schema []byte, compiled *jsonschema.Schema, decodeConfigFn func(raw map[string]any) (Config, error), ) Definition
NewWebhookDefinition builds a Definition from a WebhookVendor, the JSON-schema-described config (built by the vendor via buildInputSchema), and a DecodeConfig closure that decodes raw config, validates event types, and compiles the CEL filter. The shared wiring — HMAC authentication with a terminal unsigned Handshake response, envelope assembly with vendor-supplied event id + correlation id, content-hash event-id fallback — lives here so vendors don't reimplement it.
type DeliveryLogger ¶
type DeliveryLogger interface {
LogTriggerDelivery(context.Context, triggerrepo.TriggerInstance, EventEnvelope, DeliveryStatus, string, error)
}
func NewTriggerDeliveryLogger ¶
func NewTriggerDeliveryLogger(write func(context.Context, TriggerDeliveryLog)) DeliveryLogger
type DeliveryStatus ¶
type DeliveryStatus string
const ( DeliveryStatusFailed DeliveryStatus = "failed" DeliveryStatusSent DeliveryStatus = "sent" DeliveryStatusSkipped DeliveryStatus = "skipped" )
type EnvRequirement ¶
type EnvironmentLoader ¶
type EventEnvelope ¶
type HMACScheme ¶
type HMACScheme struct {
// NewHash returns a fresh HMAC writer keyed by the signing secret. Nil
// disables signature verification.
NewHash func(key []byte) hash.Hash
// Header names the request header carrying the signature.
Header string
// Encoding renders the computed MAC: "hex" (default) or "base64".
Encoding string
// Prefix is prepended to the encoded MAC before constant-time compare
// (e.g. "sha256=" for GitHub, "v0=" for Slack).
Prefix string
// Template shapes the bytes fed to the MAC. Placeholders: {body}, {timestamp}.
// Defaults to "{body}".
Template string
// TimestampHeader names a request header carrying a unix timestamp
// substituted into Template and bounded for replay protection. Empty
// disables timestamp checking.
TimestampHeader string
// TimestampSkew caps how far the timestamp may drift from now. Defaults
// to 300s when TimestampHeader is set.
TimestampSkew time.Duration
}
HMACScheme describes a vendor's request-signature scheme. It covers the HMAC-based schemes used by Slack, Linear, GitHub, Stripe, and most other webhook senders. NewHash is the constructor (e.g. hmac.New(sha256.New, key)); when nil, authentication is disabled (no signature is required).
type InstanceDBHook ¶
type InstanceDBHook func(ctx context.Context, dbtx pgx.Tx, instance triggerrepo.TriggerInstance) error
InstanceDBHook runs inside the transaction that mutates a trigger instance, after the primary repo write succeeds and before commit. Returning an error rolls the entire mutation back.
type NoopDispatcher ¶
type NoopDispatcher struct {
// contains filtered or unexported fields
}
func NewNoopDispatcher ¶
func NewNoopDispatcher(logger *slog.Logger) *NoopDispatcher
func (*NoopDispatcher) Dispatch ¶
func (d *NoopDispatcher) Dispatch(ctx context.Context, input Task) error
func (*NoopDispatcher) Kind ¶
func (d *NoopDispatcher) Kind() string
type ProcessScheduledInput ¶
type RoutedConfig ¶
type RoutedConfig interface {
Config
RoutingPolicy() RoutingPolicy
// RoutingFacts returns false for events that do not belong to a
// conversation.
RoutingFacts(event any) (RoutingFacts, bool)
}
RoutedConfig is a trigger config whose events belong to conversations that support thread routing.
type RoutingFacts ¶
type RoutingFacts struct {
// Addressed reports that the event is explicitly directed at the target,
// such as a mention, a direct message, or a click on the target's button.
Addressed bool
// SelfAuthored reports that the target produced the event itself.
SelfAuthored bool
// InThread reports that the event is a reply inside a conversation that
// has earlier messages.
InThread bool
// Cursor is the event's position in its conversation. Cursors of one
// conversation must sort lexically in delivery order.
Cursor string
// Conversation reports that the event is a conversation message, mention,
// or button click. Other events (reactions, joins) skip the reply rules and
// are delivered whenever they pass the trigger filter.
Conversation bool
// DedupKey identifies the underlying message when the source delivers it
// as more than one event (Slack sends both app_mention and message for a
// mention). Empty uses the event id.
DedupKey string
}
RoutingFacts are the source-specific properties of an event that thread routing reads.
type RoutingPolicy ¶
type RoutingPolicy string
RoutingPolicy selects which conversation events reach a trigger target when no thread route decides them.
const ( // RoutingPolicyMentions delivers events that address the target. The // target does not follow the thread afterwards. RoutingPolicyMentions RoutingPolicy = "mentions" // RoutingPolicyThreads delivers events that address the target and // subscribes it to their thread, then delivers every event on threads it // is subscribed to. RoutingPolicyThreads RoutingPolicy = "threads" // RoutingPolicyChannels delivers every event that passes the trigger // filter. RoutingPolicyChannels RoutingPolicy = "channels" )
type ScheduleWorkflowInput ¶
type SlackEventSummary ¶
type SlackEventSummary struct {
// Type is the request type: "url_verification" or "event_callback".
Type string
// Challenge is set on url_verification requests.
Challenge string
TeamID string
EventType string
ChannelID string
// ThreadTS is the thread the event belongs to: its parent's timestamp, or
// its own when it starts a thread.
ThreadTS string
UserID string
BotID string
Subtype string
}
SlackEventSummary is what the Speakeasy app's endpoint reads from a Slack Events API request before routing it.
func SummarizeSlackEvent ¶
func SummarizeSlackEvent(body []byte) (SlackEventSummary, error)
SummarizeSlackEvent reads a Slack Events API request body.
func (SlackEventSummary) Addressed ¶
func (s SlackEventSummary) Addressed() bool
Addressed reports whether a person sent the event to the app: a mention or a post in a direct message. Edits, deletions, and bot posts are not.
type SpeakeasySlackTokens ¶
type SpeakeasySlackTokens interface {
ProjectBotToken(ctx context.Context, organizationID string, projectID uuid.UUID) (string, error)
}
SpeakeasySlackTokens resolves the bot token of the Slack workspace whose Speakeasy app answers for a project.
type Task ¶
type Task struct {
TriggerInstanceID string
DefinitionSlug string
TargetKind string
TargetRef string
TargetDisplay string
EventID string
CorrelationID string
EventJSON []byte
RawPayload []byte
// ThreadBackfill, when set, asks Dispatch to add conversation messages the
// target has not seen to EventJSON before delivery.
ThreadBackfill *ThreadBackfill
}
type ThreadBackfill ¶
type ThreadBackfill struct {
// After is the cursor of the newest message the target has seen. Empty
// reads the conversation from its start.
After string
}
ThreadBackfill asks the dispatcher to add conversation messages the target has not seen to the event before delivery.
type ThreadRouteState ¶
type ThreadRouteState string
ThreadRouteState is whether a trigger target receives events from one conversation.
const ( ThreadRouteSubscribed ThreadRouteState = "subscribed" ThreadRouteUnsubscribed ThreadRouteState = "unsubscribed" )
type TriggerCronWorkflowInput ¶
type TriggerCronWorkflowInput struct {
TriggerInstanceID string `json:"trigger_instance_id"`
}
type TriggerDeliveryLog ¶
type TriggerDeliveryLog struct {
Timestamp time.Time
Instance triggerrepo.TriggerInstance
Attributes map[attr.Key]any
}
type TriggerDispatchWorkflowInput ¶
type TriggerDispatchWorkflowInput struct {
Task Task
}
type UpdateParams ¶
type WebhookIngest ¶
type WebhookIngest struct {
Response *WebhookResponse
Event any
EventID string
CorrelationID string
}
WebhookIngest is the result of a vendor's Ingest step: an optional inline response (e.g. Slack's url_verification challenge echo), the normalized event, and the routing metadata that NewWebhookDefinition folds into the EventEnvelope.
type WebhookIngressResult ¶
type WebhookIngressResult struct {
Response *WebhookResponse
Event *EventEnvelope
Task *Task
}
type WebhookResponse ¶
type WebhookVendor ¶
type WebhookVendor struct {
Slug string
Title string
Description string
EventType reflect.Type
EnvRequirements []EnvRequirement
SecretEnv string
Signature HMACScheme
SupportedEventTypes []string
// Authenticate replaces HMAC signature verification for vendors whose
// scheme is not a shared-secret MAC over the body (e.g. Bot Framework's
// Microsoft-signed JWTs). Exactly one of Authenticate and Signature.NewHash
// must be set; NewWebhookDefinition enforces this at construction so a
// vendor can never be silently wired with no authentication at all.
Authenticate func(ctx context.Context, body []byte, headers http.Header, env map[string]string) error
// Handshake recognizes an unsigned verification handshake (e.g. Slack's
// url_verification, which must echo a challenge before any signing secret
// is necessarily configured) and returns the response to send. A non-nil
// response is terminal: authentication skips signature verification, and
// ingress returns only that response without calling Ingest, so a request
// exempt from verification can never produce an event. May be nil, in
// which case signature verification always runs.
Handshake func(body []byte, headers http.Header) *WebhookResponse
// Ingest decodes body + headers into a normalized event for downstream
// consumers, the vendor's delivery id (used for dedup; falls back to a
// content hash when empty), and the correlation id that routes the event
// to an assistant conversation. A nil Response with a nil Event acks
// without dispatching (e.g. an unsupported Slack interaction envelope).
Ingest func(body []byte, headers http.Header) (*WebhookIngest, error)
}
WebhookVendor is the per-vendor description a webhook trigger implementation supplies. NewWebhookDefinition assembles the shared Definition wiring (authenticate via HMACScheme, ingest into a normalized EventEnvelope, default-deny event-type filtering) around it, so adding a new webhook source is mostly a matter of describing its signature scheme, env var, event types, and an Ingest function that decodes the body into a typed event plus correlation id.