notify

Documentation

Overview

Package notify delivers run-completion webhooks — a generic "this run reached a terminal state, here is its final answer" callback POSTed to a URL supplied at launch time.

This is the engine-side primitive that lets an external integration (a chat adapter, a CI bridge, anything) trigger a run asynchronously and be told when it finished without polling. It is deliberately neutral: the payload is a plain JSON envelope; the platform-specific glue (Slack/Mattermost formatting, thread routing) lives entirely in the receiver.

The callback URL is treated as attacker-influenced (it arrives over the launch API), so every delivery passes an SSRF guard: only http/https, and — unless explicitly opted in — never a loopback, link-local, RFC-1918, or cloud-metadata host. Resolution fails closed.

Index

• Constants
• func Sign(secret string, body []byte) string
• func Verify(secret string, body []byte, header string) bool
• type CompletionPayload
• type Notifier
  • func New(logger *iterlog.Logger, timeout time.Duration, opts ...Option) *Notifier
  • func (n *Notifier) FireForRun(ctx context.Context, st store.RunStore, runID string)
• type Option
  • func WithAllowPrivate(allow bool) Option
  • func WithSigningSecret(secret string) Option

Constants

const DefaultAnswerField = "final_answer"

DefaultAnswerField is the artifact-data key the notifier reads to populate CompletionPayload.FinalAnswer when no explicit field is configured on the run.

const PayloadVersion = 1

PayloadVersion is the schema version of CompletionPayload. Bumped on any breaking change so receivers can gate on it.

const SignatureHeader = "X-Iterion-Signature"

SignatureHeader is the HTTP header carrying the HMAC of a webhook body. Receivers read it and recompute the MAC over the raw body to authenticate the sender.

Functions

func Sign

func Sign(secret string, body []byte) string

Sign returns the header value authenticating body under secret: "sha256=" followed by the lowercase-hex HMAC-SHA256. An empty secret yields an empty string — callers treat that as "signing disabled" and send no signature header.

This is the shared primitive for BOTH directions of iterion's webhook auth: the completion notifier signs outbound payloads with it, and any future native inbound webhook (POST → trigger a run) would verify incoming requests with Verify below. Keep it dependency-free.

func Verify

func Verify(secret string, body []byte, header string) bool

Verify reports whether header is a valid signature for body under secret. The comparison is constant-time to avoid leaking the expected MAC through timing. A mismatched length, missing prefix, or non-hex header all return false.

When secret is empty, Verify returns false for every input — an unconfigured receiver must reject signed and unsigned requests alike rather than silently accept everything. Callers that want to allow unauthenticated requests must branch on "secret configured?" before calling Verify, making that choice explicit at the call site.

Types

type CompletionPayload

type CompletionPayload struct {
	V             int    `json:"v"`
	RunID         string `json:"run_id"`
	Status        string `json:"status"`
	WorkflowName  string `json:"workflow_name,omitempty"`
	FinalAnswer   string `json:"final_answer,omitempty"`
	FinalAnswerN  string `json:"final_answer_node,omitempty"`
	Error         string `json:"error,omitempty"`
	CallbackToken string `json:"callback_token,omitempty"`
}

CompletionPayload is the JSON body POSTed to a run's callback URL when the run reaches a terminal state. Stable wire contract — see docs/outbound-callbacks.md.

type Notifier

type Notifier struct {
	// contains filtered or unexported fields
}

Notifier delivers CompletionPayloads. Construct once and share; it is safe for concurrent use. A nil *Notifier is a valid no-op so callers can hold one unconditionally.

func New

func New(logger *iterlog.Logger, timeout time.Duration, opts ...Option) *Notifier

New builds a Notifier. timeout bounds each delivery attempt; zero applies a 15s default.

func (*Notifier) FireForRun

func (n *Notifier) FireForRun(ctx context.Context, st store.RunStore, runID string)

FireForRun loads the run, and if it carries a callback URL and has reached a terminal-for-notification state, resolves its final answer and POSTs a CompletionPayload. Best-effort: every failure is logged, none is returned — a webhook delivery must never affect run outcome.

Paused states (paused_waiting_human / paused_operator) are skipped: the run is not done, it is waiting. Resume will call FireForRun again when the run actually terminates.

type Option

type Option func(*Notifier)

Option configures a Notifier.

func WithAllowPrivate

func WithAllowPrivate(allow bool) Option

WithAllowPrivate permits callback URLs that resolve to loopback, link-local, RFC-1918, or cloud-metadata addresses. Off by default (SSRF guard). Turn it on only for self-hosted deployments where the callback receiver genuinely lives on a private network alongside iterion.

func WithSigningSecret

func WithSigningSecret(secret string) Option

WithSigningSecret sets the shared secret used to HMAC-sign every outbound completion payload (see Sign). When set, each delivery carries an X-Iterion-Signature header the receiver verifies to authenticate that iterion — not a forger who learned the callback URL — sent it. Empty (the default) disables signing: no header is added, and a receiver expecting one should reject the request.