Documentation
¶
Overview ¶
Package webhooks sends signed HTTP notifications of site events (content, media, menus, forms, sign-ins, orders, migrations) to subscribed endpoints, with retries, a delivery log, redelivery and secret rotation.
Index ¶
- Constants
- Variables
- func RedactURL(raw string) string
- func Sign(secret string, ts int64, body []byte) string
- func Verify(secret, signature string, ts int64, body []byte, now time.Time, ...) bool
- type CreateResponse
- type DeleteResponse
- type Delivery
- type Event
- type Input
- type Module
- type Service
- type ValidationError
- type Webhook
Constants ¶
const Perm = "webhooks.manage"
Perm is the permission for managing webhooks.
const TestEvent = "webhook.test"
TestEvent is sent by Test; webhooks need not subscribe to it.
Variables ¶
var ( // ErrNotFound is returned for an unknown webhook or delivery. ErrNotFound = errors.New("webhooks: not found") // ErrInactive is returned when testing or redelivering to a disabled webhook. ErrInactive = errors.New("webhooks: webhook is disabled") )
Functions ¶
func RedactURL ¶
RedactURL returns raw as origin + path, with "?…" in place of any query string: endpoints often carry a token there. Lists, the audit log and list API responses show this form; storage and the edit views keep the full URL. An unparsable URL redacts to "".
Types ¶
type CreateResponse ¶
type CreateResponse struct {
Webhook Webhook `json:"webhook"`
Secret string `json:"secret" doc:"whsec_…; sign check: sha256=hex(HMAC-SHA256(secret, timestamp + \".\" + body))"`
}
CreateResponse is returned once by POST /v1/webhooks and POST /v1/webhooks/{id}/secret: secret is never shown again.
type DeleteResponse ¶
DeleteResponse is returned by DELETE /v1/webhooks/{id}.
type Delivery ¶
type Delivery struct {
ID string `json:"id"`
WebhookID string `json:"webhook_id"`
Event string `json:"event"`
Status string `json:"status" doc:"queued | delivered | retrying | failed"`
Attempts int `json:"attempts"`
ResponseCode int `json:"response_code"`
Error string `json:"error"`
DurationMS int `json:"duration_ms"`
CreatedAt string `json:"created_at"`
DeliveredAt string `json:"delivered_at"`
Payload string `json:"payload,omitempty" doc:"the signed JSON body; returned by the deliveries list"`
}
Delivery is one event sent (or being retried) to one webhook.
type Input ¶
type Input struct {
Name *string `json:"name,omitempty"`
URL *string `json:"url,omitempty"`
Events []string `json:"events,omitempty"`
Active *bool `json:"active,omitempty"`
}
Input is the writable state of a webhook (create, or update: nil fields keep).
type Module ¶
type Module struct{}
Module is the webhooks kernel.Module.
type Service ¶
type Service interface {
List(ctx context.Context) ([]Webhook, error)
Get(ctx context.Context, id string) (*Webhook, error)
Create(ctx context.Context, in Input) (*Webhook, string, error)
Update(ctx context.Context, id string, in Input) (*Webhook, error)
Delete(ctx context.Context, id string) error
RotateSecret(ctx context.Context, id string) (string, error)
Test(ctx context.Context, id string) (*Delivery, error)
Deliveries(ctx context.Context, webhookID string, limit int) ([]Delivery, error)
Redeliver(ctx context.Context, deliveryID string) (*Delivery, error)
}
Service manages webhooks (kernel.ServiceWebhooks).
type ValidationError ¶
ValidationError lists invalid fields as i18n keys.
func (*ValidationError) Error ¶
func (e *ValidationError) Error() string
type Webhook ¶
type Webhook struct {
ID string `json:"id"`
Name string `json:"name"`
URL string `json:"url" doc:"lists show origin and path only (query as ?…); get returns the full URL"`
Events []string `json:"events" doc:"event names, or [\"*\"] for every event"`
Active bool `json:"active"`
ConsecutiveFailures int `json:"consecutive_failures"`
LastStatus string `json:"last_status" doc:"\"\" | delivered | retrying | failed"`
LastDeliveryAt string `json:"last_delivery_at"`
CreatedAt string `json:"created_at"`
UpdatedAt string `json:"updated_at"`
}
Webhook is an endpoint subscribed to site events.
Source Files