webhooks

package
v0.16.0 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: Apache-2.0 Imports: 30 Imported by: 0

Documentation

Overview

Package webhooks sends signed events to endpoints that owners register.

Index

Constants

View Source
const (
	HeaderEventID   = "X-Skael-Event-Id"
	HeaderEventType = "X-Skael-Event-Type"
	HeaderTimestamp = "X-Skael-Timestamp"
	HeaderSignature = "X-Skael-Signature"
)

The headers each delivery carries.

View Source
const (
	EventVersionPublished = "skill.version.published"
	EventVersionApproved  = "skill.version.approved"
	EventSetChanged       = "set.changed"
	EventSubmissionDone   = "submission.decided"
)

The event types.

Variables

View Source
var ErrRefusedAddress = errors.New("refused address")

ErrRefusedAddress reports an address a delivery may not reach.

EventTypes lists what an endpoint can subscribe to.

Functions

func NewClient

func NewClient(allowPrivate bool) *http.Client

NewClient returns the HTTP client for deliveries. The control function runs on the resolved IP of every connection, including each redirect, so DNS rebinding and a redirect to a metadata service both fail at dial.

func RegisterRoutes

func RegisterRoutes(api huma.API, pool *pgxpool.Pool, store *Store, notifier *Notifier, allowPrivate bool)

RegisterRoutes wires endpoint management. Only instance owners and admins reach it, because an endpoint receives data about every matching skill.

func Sign

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

Sign returns the hex HMAC-SHA256 of "<timestamp>.<body>".

func SignatureHeader

func SignatureHeader(timestamp int64, body []byte, secrets ...string) string

SignatureHeader signs with each live secret, so a consumer holding the old secret still verifies during a rotation window.

func ValidateURL

func ValidateURL(ctx context.Context, raw string, allowPrivate bool) error

ValidateURL gives an early answer when an endpoint is saved. The check that protects anything is the dial control in NewClient, because a name can change what it resolves to after this returns.

Types

type Attempt

type Attempt struct {
	ResponseCode *int      `json:"response_code"`
	Error        string    `json:"error,omitempty"`
	Succeeded    bool      `json:"succeeded"`
	CreatedAt    time.Time `json:"created_at"`
}

Attempt is one try at a delivery.

type Delivery

type Delivery struct {
	ID        string    `json:"id"`
	EventID   string    `json:"event_id"`
	EventType string    `json:"event_type"`
	State     string    `json:"state"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
	Attempts  []Attempt `json:"attempts"`
}

Delivery is one event for one endpoint, with every attempt.

type DeliveryArgs

type DeliveryArgs struct {
	DeliveryID string `json:"delivery_id"`
}

DeliveryArgs holds an id and nothing else. River UI shows arguments to admins, and a payload or a secret must not appear there.

func (DeliveryArgs) InsertOpts

func (DeliveryArgs) InsertOpts() river.InsertOpts

InsertOpts implements river.JobArgsWithInsertOpts.

func (DeliveryArgs) Kind

func (DeliveryArgs) Kind() string

Kind implements river.JobArgs.

type DeliveryWorker

type DeliveryWorker struct {
	river.WorkerDefaults[DeliveryArgs]
	// contains filtered or unexported fields
}

DeliveryWorker sends one attempt of one delivery.

func NewDeliveryWorker

func NewDeliveryWorker(store *Store, allowPrivate bool) *DeliveryWorker

NewDeliveryWorker constructs the worker.

func (*DeliveryWorker) NextRetry

func (w *DeliveryWorker) NextRetry(job *river.Job[DeliveryArgs]) time.Time

NextRetry doubles from one minute up to maxBackoff.

func (*DeliveryWorker) Timeout

Timeout bounds one attempt beyond the HTTP client's own limit.

func (*DeliveryWorker) Work

Work sends the event. Returning an error makes River retry, and the state becomes failed only on the attempt River will not repeat.

type Endpoint

type Endpoint struct {
	ID         string    `json:"id"`
	Name       string    `json:"name"`
	URL        string    `json:"url"`
	EventTypes []string  `json:"event_types"`
	SetIDs     []string  `json:"set_ids"`
	Enabled    bool      `json:"enabled"`
	CreatedBy  string    `json:"created_by"`
	CreatedAt  time.Time `json:"created_at"`

	PreviousExpiresAt *time.Time `json:"previous_secret_expires_at,omitempty"`
	// contains filtered or unexported fields
}

Endpoint is a registered receiver. Its secrets never leave through this type.

type Envelope

type Envelope struct {
	ID   string    `json:"id"`
	Type string    `json:"type"`
	Time time.Time `json:"time"`
	Data any       `json:"data"`
}

Envelope is the JSON body of every delivery.

type JobInserter

type JobInserter interface {
	InsertTx(ctx context.Context, tx pgx.Tx, args river.JobArgs, opts *river.InsertOpts) (*rivertype.JobInsertResult, error)
}

JobInserter is the part of the River client that enqueues in a transaction.

type Notifier

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

Notifier turns a change into events inside the transaction that made the change, so a crash cannot lose an event and a rollback cannot invent one.

func NewNotifier

func NewNotifier(inserter JobInserter, setStore *sets.Store) *Notifier

NewNotifier constructs a Notifier.

func (*Notifier) Redeliver

func (n *Notifier) Redeliver(ctx context.Context, pool beginner, deliveryID string) (bool, error)

Redeliver sends a delivery again with the same event id.

func (*Notifier) SendTest

func (n *Notifier) SendTest(ctx context.Context, pool beginner, endpointID string) error

SendTest emits a test event to one endpoint, and redeliver re-enqueues with the same event id: both run in their own transaction.

func (*Notifier) SetChanged

func (n *Notifier) SetChanged(ctx context.Context, tx pgx.Tx, setID string) error

SetChanged implements sets.ChangeNotifier. It emits only when the set's resolution id differs, so an unrelated release and an unchanged pin are quiet.

func (*Notifier) SkillChanged

func (n *Notifier) SkillChanged(ctx context.Context, tx pgx.Tx, skillName string) error

SkillChanged implements skill.ChangeNotifier: it rechecks each set that names the skill or one of its aliases.

func (*Notifier) SubmissionDecided

func (n *Notifier) SubmissionDecided(ctx context.Context, tx pgx.Tx, sub *submissions.Submission) error

SubmissionDecided implements submissions.ChangeNotifier.

func (*Notifier) VersionReleased

func (n *Notifier) VersionReleased(ctx context.Context, tx pgx.Tx, ev skill.ReleaseEvent) error

VersionReleased implements skill.ChangeNotifier. A publish the gate holds never reaches it, so a held version has no event.

type SetChangedData

type SetChangedData struct {
	SetID        string               `json:"set_id"`
	Set          string               `json:"set"`
	ResolutionID string               `json:"resolution_id"`
	Complete     bool                 `json:"complete"`
	Skills       []sets.ResolvedEntry `json:"skills"`
}

SetChangedData is the data of set.changed. It holds no skill content, so a webhook cannot go around a set-limited key.

type Store

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

Store persists endpoints and the delivery log.

func NewStore

func NewStore(pool *pgxpool.Pool) *Store

NewStore constructs a Store.

func (*Store) Deliveries

func (s *Store) Deliveries(ctx context.Context, endpointID string, limit int) ([]Delivery, error)

Deliveries lists an endpoint's newest deliveries with their attempts.

func (*Store) Get

func (s *Store) Get(ctx context.Context, id string) (*Endpoint, error)

Get returns an endpoint, or nil.

func (*Store) List

func (s *Store) List(ctx context.Context) ([]Endpoint, error)

List returns every endpoint.

func (*Store) Rotate

func (s *Store) Rotate(ctx context.Context, id, secret string, window time.Duration) (*Endpoint, error)

Rotate replaces the secret and keeps the old one valid for the window.

type SubmissionData

type SubmissionData struct {
	SubmissionID string `json:"submission_id"`
	Skill        string `json:"skill"`
	State        string `json:"state"`
	Consumer     string `json:"consumer"`
	Version      *int   `json:"version,omitempty"`
}

SubmissionData is the data of submission.decided. A rejection's reason stays behind the API, which checks who reads it.

type VersionData

type VersionData struct {
	Skill   string `json:"skill"`
	Version int    `json:"version"`
	SHA256  string `json:"sha256"`
}

VersionData is the data of the skill version events.

type WebhookEndpointWithSecret

type WebhookEndpointWithSecret struct {
	Endpoint
	Secret string `json:"secret" doc:"Shown once."`
}

WebhookEndpointWithSecret returns the secret once, at create and at rotate.

Jump to

Keyboard shortcuts

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