README
¶
togo-framework/webhooks
Outgoing webhooks for togo — signed, retried, async event delivery to subscribers.
Install
togo install togo-framework/webhooks
The togo answer to Spatie's webhook-server / Svix. Register subscriptions, then
Send an event — every matching subscriber gets an HMAC-SHA256-signed POST,
delivered over the queue with exponential-backoff retries (inline when no
queue is configured). Every attempt is recorded in a delivery log.
Usage
s, _ := webhooks.FromKernel(k)
// Subscribe an endpoint to events ("*" = all).
sub := s.Subscribe("https://acme.test/hooks", []string{"order.paid"}, "whsec_secret")
// Fire an event — delivered async to every matching subscriber.
s.Send(ctx, "order.paid", map[string]any{"id": 42, "total": 19.99})
// Inspect deliveries.
for _, d := range s.Deliveries() { /* d.Succeeded, d.Status, d.Attempt … */ }
Signing & verification
Each delivery carries X-Webhook-Signature: t=<unix>,v1=<hmac> (+ X-Webhook-Timestamp).
Receivers verify with:
ok := webhooks.Verify(secret, r.Header.Get("X-Webhook-Signature"), body)
REST API
| Method | Path | Purpose |
|---|---|---|
GET |
/api/webhooks/subscriptions |
list subscriptions |
POST |
/api/webhooks/subscriptions |
{url, events, secret} |
DELETE |
/api/webhooks/subscriptions/{id} |
remove |
POST |
/api/webhooks/send |
{event, data} |
GET |
/api/webhooks/deliveries |
delivery log |
Configuration
No required env. Uses the kernel Queue for async delivery + retries when
present (togo install togo-framework/queue + a worker); otherwise delivers
inline. Retries up to 5 attempts on non-2xx.
Documentation
¶
Overview ¶
Package webhooks delivers outgoing webhooks to subscribers — signed, asynchronous, and retried (Spatie webhook-server / Svix style for togo).
Register subscriptions (a URL + the events it wants + a signing secret), then Send an event: every matching subscriber receives an HMAC-SHA256-signed POST, delivered over the kernel Queue (with exponential-backoff retries) when one is configured, or inline otherwise. Every attempt is recorded in a delivery log.
s, _ := webhooks.FromKernel(k)
sub := s.Subscribe("https://acme.test/hooks", []string{"order.paid"}, "whsec_…")
s.Send(ctx, "order.paid", map[string]any{"id": 42})
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Delivery ¶
type Delivery struct {
ID string `json:"id"`
SubID string `json:"subscription_id"`
Event string `json:"event"`
Attempt int `json:"attempt"`
Status int `json:"status"`
Succeeded bool `json:"succeeded"`
Error string `json:"error,omitempty"`
At time.Time `json:"at"`
}
Delivery records a single delivery attempt.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service is the webhooks runtime stored on the kernel (k.Get("webhooks")).
func FromKernel ¶
FromKernel returns the webhooks Service registered on the kernel.
func (*Service) Deliveries ¶
Deliveries returns the recent delivery log (most recent last).
func (*Service) Send ¶
Send dispatches an event to every matching subscriber. Delivery is async over the queue when available, else inline.
func (*Service) Subscribe ¶
func (s *Service) Subscribe(url string, events []string, secret string) *Subscription
Subscribe registers an endpoint for the given events ("*" = all).
func (*Service) Subscriptions ¶
func (s *Service) Subscriptions() []Subscription
Subscriptions lists all registered subscriptions.
func (*Service) Unsubscribe ¶
Unsubscribe removes a subscription.
Source Files