webhook

package
v0.0.25 Latest Latest
Warning

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

Go to latest
Published: Oct 29, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package webhook is the built-in webhook provider: a signed HTTP POST of JSON to a URL the product names on every call, signed per Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature: HMAC-SHA256 with the secret the product holds for that receiver). Retries are the platform's (the activity's); the receiver deduplicates by webhook-id, the same on every attempt.

Index

Constants

View Source
const (
	// CodeForbidden: a URL courier does not post to — not https, a host the
	// channel does not allow, or an internal address.
	CodeForbidden = "forbidden_destination"
	// CodeGone: the receiver answered 410, it takes no more.
	CodeGone = "gone"
	// CodeRefused: the receiver answered another 3xx or 4xx.
	CodeRefused = "refused"
)

Codes of the refusals.

View Source
const (
	HeaderID        = "Webhook-Id"
	HeaderTimestamp = "Webhook-Timestamp"
	HeaderSignature = "Webhook-Signature"
)

Signature headers (Standard Webhooks: webhook-id, webhook-timestamp, webhook-signature), canonical.

View Source
const (
	MaxBodyBytes = 1 << 20
)

Limits of a message.

Variables

View Source
var (
	ErrURL         = errors.New("webhook: url is an https URL")
	ErrDestination = errors.New("webhook: url is not a host this channel allows")
	ErrSecret      = errors.New("webhook: secret is required (raw, or whsec_ and base64)")
	ErrBody        = errors.New("webhook: body is a JSON value")
	ErrTooBig      = errors.New("webhook: body exceeds 1 MiB")
	ErrID          = errors.New("webhook: id is up to 256 printable characters")
	ErrHeader      = errors.New("webhook: header")
)

Errors of Validate; every one is final.

Functions

func Sign

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

Sign is the webhook-signature of a message: "v1," and the base64 HMAC-SHA256 of "<id>.<timestamp>.<body>" with the secret.

Types

type Client

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

Client posts the webhooks of one channel.

func New

func New(cfg Config, client *http.Client) *Client

New is the client of a channel. A nil client: one that does not follow redirects and, unless the channel is insecure, dials only public addresses, directly (netguard.ErrForbiddenAddress).

func (*Client) Check

func (c *Client) Check(context.Context) error

Check: nothing to try before a receiver is named.

func (*Client) Config

func (c *Client) Config() Config

Config of the channel.

func (*Client) Send

func (c *Client) Send(ctx context.Context, m Message, id string) (string, error)

Send signs and posts m (validated) with webhook-id id and returns it, or a *provider.Error: final for a refusal, later for a rate limit or an unavailable receiver that says when to come back; any other failure is retried.

type Config

type Config struct {
	// Hosts the channel posts to (exact or *.suffix); empty: any public
	// host.
	Hosts []string `json:"hosts,omitempty" schemapb:"description=Hosts webhooks may go to, else any public host"`
	// Insecure lets the channel post over http and to internal addresses:
	// a receiver in the installation's own network, or development.
	Insecure bool `json:"insecure,omitempty" schemapb:"description=Allow http and internal addresses"`
}

Config of a webhook channel.

type Message

type Message struct {
	Channel string `json:"channel,omitempty" schemapb:"description=Webhook channel of the installation, else the default"`
	URL     string `json:"url"               schemapb:"description=Receiver URL"`
	// Secret signs the message, raw or whsec_ and base64; the product
	// keeps one per receiver.
	Secret string `json:"secret" schemapb:"secret=true;description=Signing secret of the receiver"`
	// ID is webhook-id, the receiver deduplicates by it; empty: the
	// step's, the same on every attempt.
	ID      string            `json:"id,omitempty"      schemapb:"description=webhook-id, else the step's"`
	Body    json.RawMessage   `json:"body"              schemapb:"description=JSON posted as the body"`
	Headers map[string]string `json:"headers,omitempty" schemapb:"description=Extra request headers"`
}

Message is courier.SendWebhook's input.

func (Message) Target

func (m Message) Target() string

Target names the message in logs and audit: the URL's host.

func (Message) Validate

func (m Message) Validate(cfg Config) error

Validate m for a channel of cfg.

Jump to

Keyboard shortcuts

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