Self-hosted email delivery platform that enables applications to send emails via HTTP APIs while handling SMTP delivery, templates, storage, security, and analytics. Fully self-hostable alternative to services like SendGrid or Mailgun.
Go email-relayemail-routinghttp-to-smtpmail-deliverymailchimp-alternativemailgun-alternativemailsendermailservermailtemplatemailtestpostmark-alternativesend-emailsendgrid-alternativesendmailtransactional-emailtransactional-outbox
// Copyright (c) 2026 Jonas Kaninda.
//
// This file is part of Posta.
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Affero General Public License for more details.
//
// You should have received a copy of the GNU Affero General Public License
// along with this program. If not, see <https://www.gnu.org/licenses/>.
//
// SPDX-License-Identifier: AGPL-3.0-or-later
package webhook
import (
"bytes"
"context"
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"fmt"
"net"
"net/http"
"net/mail"
"net/url"
"strings"
"time"
"github.com/jkaninda/logger"
"golang.org/x/net/http/httpproxy"
"golang.org/x/net/proxy"
"github.com/goposta/posta/internal/models"
"github.com/goposta/posta/internal/netguard"
"github.com/goposta/posta/internal/storage/repositories"
)
const (
defaultMaxRetries = 3
defaultRetryBaseWait = 2 * time.Second
defaultTimeout = 10 * time.Second
)
// Config holds configurable settings for the webhook dispatcher.
type Config struct {
MaxRetries int
Timeout time.Duration
// ProxyURL routes all outbound webhook requests through a proxy,
// hiding the server's IP address from webhook endpoints.
// Supports http://, https://, and socks5:// schemes.
ProxyURL string
// Network decides which addresses webhooks may reach. The zero value
// blocks private and reserved addresses.
Network netguard.Policy
}
type Dispatcher struct {
repo *repositories.WebhookRepository
deliveryRepo *repositories.WebhookDeliveryRepository
client *http.Client
network netguard.Policy
proxied bool // a proxy dials the target, so the dialer cannot check it
maxRetries int
onDeliverySuccess func()
onDeliveryFailed func()
onDeliveryDone func(float64) // duration in seconds
}
func NewDispatcher(repo *repositories.WebhookRepository) *Dispatcher {
d := &Dispatcher{
repo: repo,
maxRetries: defaultMaxRetries,
client: &http.Client{
Timeout: defaultTimeout,
// A webhook URL is checked where it points; a redirect could
// send the request somewhere else, so it is not followed.
CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse },
},
}
d.client.Transport = d.guardedTransport()
return d
}
// guardedTransport dials only the addresses the network policy allows. It
// checks each address as it connects, so neither a hostname resolving to a
// private address nor a DNS answer that changed since the webhook was saved
// gets through.
//
// A proxy set in HTTP_PROXY or HTTPS_PROXY is still used, as Go's default
// transport would: the connection to it is allowed wherever it is, and the
// target, which only the proxy dials, is checked by name instead.
func (d *Dispatcher) guardedTransport() *http.Transport {
env := httpproxy.FromEnvironment()
proxyFor := env.ProxyFunc()
proxies := map[string]bool{}
for _, raw := range []string{env.HTTPProxy, env.HTTPSProxy} {
if u, err := url.Parse(raw); err == nil && u.Host != "" {
port := u.Port()
if port == "" {
port = map[string]string{"https": "443"}[u.Scheme]
if port == "" {
port = "80"
}
}
proxies[net.JoinHostPort(u.Hostname(), port)] = true
}
}
t := http.DefaultTransport.(*http.Transport).Clone()
t.Proxy = func(req *http.Request) (*url.URL, error) {
u, err := proxyFor(req.URL)
if u != nil && err == nil {
if cerr := d.network.CheckURL(req.Context(), req.URL.String()); cerr != nil {
return nil, fmt.Errorf("%w: %v", netguard.ErrBlocked, cerr)
}
}
return u, err
}
t.DialContext = func(ctx context.Context, network, addr string) (net.Conn, error) {
if proxies[addr] {
return (&net.Dialer{Timeout: 30 * time.Second}).DialContext(ctx, network, addr)
}
return d.network.DialContext(ctx, network, addr)
}
return t
}
// Network returns the policy webhook URLs are checked against.
func (d *Dispatcher) Network() netguard.Policy {
return d.network
}
// SetConfig applies configurable settings to the dispatcher.
func (d *Dispatcher) SetConfig(cfg Config) {
if cfg.MaxRetries > 0 {
d.maxRetries = cfg.MaxRetries
}
if cfg.Timeout > 0 {
d.client.Timeout = cfg.Timeout
}
d.network = cfg.Network
d.client.Transport = d.guardedTransport()
if cfg.ProxyURL != "" {
transport, err := proxyTransport(cfg.ProxyURL)
if err != nil {
logger.Error("invalid webhook proxy URL, requests will be sent directly", "error", err)
return
}
d.client.Transport = transport
d.proxied = true
logger.Info("webhook proxy configured", "proxy", cfg.ProxyURL)
}
}
// proxyTransport builds an *http.Transport that routes requests through the
// given proxy URL. Supported schemes: http, https, socks5.
func proxyTransport(rawURL string) (*http.Transport, error) {
parsed, err := url.Parse(rawURL)
if err != nil {
return nil, fmt.Errorf("failed to parse proxy URL: %w", err)
}
switch parsed.Scheme {
case "http", "https":
return &http.Transport{
Proxy: http.ProxyURL(parsed),
}, nil
case "socks5":
auth := &proxy.Auth{}
if parsed.User != nil {
auth.User = parsed.User.Username()
auth.Password, _ = parsed.User.Password()
} else {
auth = nil
}
dialer, err := proxy.SOCKS5("tcp", parsed.Host, auth, proxy.Direct)
if err != nil {
return nil, fmt.Errorf("failed to create SOCKS5 dialer: %w", err)
}
contextDialer, ok := dialer.(proxy.ContextDialer)
if !ok {
return nil, fmt.Errorf("SOCKS5 dialer does not support DialContext")
}
return &http.Transport{
DialContext: func(ctx context.Context, network, addr string) (net.Conn, error) {
return contextDialer.DialContext(ctx, network, addr)
},
}, nil
default:
return nil, fmt.Errorf("unsupported proxy scheme %q (use http, https, or socks5)", parsed.Scheme)
}
}
// SetDeliveryRepo sets the repository used to record delivery attempts.
func (d *Dispatcher) SetDeliveryRepo(repo *repositories.WebhookDeliveryRepository) {
d.deliveryRepo = repo
}
// OnDeliverySuccess sets a callback invoked after each successful webhook delivery.
func (d *Dispatcher) OnDeliverySuccess(fn func()) { d.onDeliverySuccess = fn }
// OnDeliveryFailed sets a callback invoked after each failed webhook delivery.
func (d *Dispatcher) OnDeliveryFailed(fn func()) { d.onDeliveryFailed = fn }
// OnDeliveryDone sets a callback invoked after each delivery attempt with its duration.
func (d *Dispatcher) OnDeliveryDone(fn func(float64)) { d.onDeliveryDone = fn }
type Payload struct {
Event string `json:"event"`
EmailID string `json:"email_id"`
Timestamp string `json:"timestamp"`
}
// CampaignPayload is the outbound shape for campaign lifecycle events
// (campaign.started, campaign.completed).
type CampaignPayload struct {
Event string `json:"event"`
CampaignID uint `json:"campaign_id"`
Name string `json:"name"`
Timestamp string `json:"timestamp"`
}
// Dispatch sends webhook notifications for the given event using the default
// outbound payload shape ({event, email_id, timestamp}). Runs asynchronously.
// workspaceID scopes which webhooks fire: nil targets the user's personal
// webhooks, a value targets that workspace's webhooks.
func (d *Dispatcher) Dispatch(userID uint, workspaceID *uint, event string, emailID string, from string) {
payload := Payload{
Event: event,
EmailID: emailID,
Timestamp: time.Now().UTC().Format(time.RFC3339),
}
body, err := json.Marshal(payload)
if err != nil {
logger.Error("failed to marshal webhook payload", "error", err)
return
}
d.DispatchJSON(userID, workspaceID, event, body, from)
}
// DispatchCampaign sends webhook notifications for a campaign lifecycle event
// using the campaign payload shape ({event, campaign_id, name, timestamp}).
// Scoping follows the same rules as Dispatch. Runs asynchronously.
func (d *Dispatcher) DispatchCampaign(userID uint, workspaceID *uint, event string, campaignID uint, name string, from string) {
payload := CampaignPayload{
Event: event,
CampaignID: campaignID,
Name: name,
Timestamp: time.Now().UTC().Format(time.RFC3339),
}
body, err := json.Marshal(payload)
if err != nil {
logger.Error("failed to marshal campaign webhook payload", "error", err)
return
}
d.DispatchJSON(userID, workspaceID, event, body, from)
}
// DispatchJSON sends a pre-serialized JSON body to all webhooks subscribed to event
// within the given scope (personal when workspaceID is nil, otherwise the
// workspace) that pass the sender-address filter. Runs asynchronously.
// Callers own the payload shape — this is the escape hatch used by the inbound
// pipeline (which has a richer payload than the outbound Payload struct).
func (d *Dispatcher) DispatchJSON(userID uint, workspaceID *uint, event string, body []byte, fromAddr string) {
go func() {
scope := repositories.ResourceScope{UserID: userID, WorkspaceID: workspaceID}
webhooks, err := d.repo.FindByScopeAndEvent(scope, event)
if err != nil {
logger.Error("failed to find webhooks", "error", err)
return
}
for _, wh := range webhooks {
if !matchesFilters(wh.Filters, fromAddr) {
continue
}
d.deliverWithRetry(userID, wh, body, event)
}
}()
}
// DispatchJSONTo sends body to the named webhooks of a workspace, as a routing
// rule asks. A webhook already subscribed to event is skipped: DispatchJSON
// delivers to it, and it must not get the payload twice. Runs asynchronously.
func (d *Dispatcher) DispatchJSONTo(workspaceID uint, webhookIDs []uint, event string, body []byte) {
if len(webhookIDs) == 0 {
return
}
go func() {
for _, id := range webhookIDs {
wh, err := d.repo.FindByID(id)
if err != nil || wh.WorkspaceID == nil || *wh.WorkspaceID != workspaceID {
continue
}
subscribed := false
for _, e := range wh.Events {
subscribed = subscribed || e == event
}
if subscribed {
continue
}
d.deliverWithRetry(wh.UserID, *wh, body, event)
}
}()
}
// matchesFilters checks if the sender address matches the webhook's filters.
func matchesFilters(filters []string, from string) bool {
if len(filters) == 0 {
return true
}
if from == "" {
return true
}
addr := from
if parsed, err := mail.ParseAddress(from); err == nil {
addr = parsed.Address
}
addr = strings.ToLower(addr)
domain := ""
if parts := strings.SplitN(addr, "@", 2); len(parts) == 2 {
domain = parts[1]
}
for _, f := range filters {
f = strings.ToLower(strings.TrimSpace(f))
if f == "" {
continue
}
if f == addr {
return true
}
if domain != "" && f == domain {
return true
}
}
return false
}
// deliverWithRetry attempts to deliver a webhook with exponential backoff retries.
func (d *Dispatcher) deliverWithRetry(userID uint, wh models.Webhook, body []byte, event string) {
var lastErr string
var lastStatus int
start := time.Now()
for attempt := 1; attempt <= d.maxRetries; attempt++ {
statusCode, err := d.doRequest(wh.URL, wh.Secret, body)
lastStatus = statusCode
if err == nil && statusCode < 300 {
d.recordDelivery(userID, wh.ID, wh.WorkspaceID, event, models.WebhookDeliverySuccess, statusCode, "", attempt)
if d.onDeliverySuccess != nil {
d.onDeliverySuccess()
}
if d.onDeliveryDone != nil {
d.onDeliveryDone(time.Since(start).Seconds())
}
logger.Info("webhook delivered", "url", wh.URL, "event", event, "attempt", attempt)
return
}
if err != nil {
// The delivery log is read by workspace members: it says what went
// wrong, not which address or port answered. The server log keeps
// the full error.
lastErr = netguard.Describe(err)
logger.Warn("webhook delivery failed", "url", wh.URL, "attempt", attempt, "error", err)
} else if statusCode < 400 {
lastErr = fmt.Sprintf("HTTP %d: redirects are not followed", statusCode)
logger.Warn("webhook redirected", "url", wh.URL, "attempt", attempt, "status", statusCode)
} else {
lastErr = fmt.Sprintf("HTTP %d", statusCode)
logger.Warn("webhook returned error status", "url", wh.URL, "attempt", attempt, "status", statusCode)
}
if attempt < d.maxRetries {
time.Sleep(defaultRetryBaseWait * time.Duration(attempt))
}
}
// All retries exhausted
d.recordDelivery(userID, wh.ID, wh.WorkspaceID, event, models.WebhookDeliveryFailed, lastStatus, lastErr, d.maxRetries)
if d.onDeliveryFailed != nil {
d.onDeliveryFailed()
}
if d.onDeliveryDone != nil {
d.onDeliveryDone(time.Since(start).Seconds())
}
}
// signPayload computes an HMAC-SHA256 signature of body using the given secret.
func signPayload(secret string, body []byte) string {
mac := hmac.New(sha256.New, []byte(secret))
mac.Write(body)
return hex.EncodeToString(mac.Sum(nil))
}
// doRequest sends a single HTTP POST to the webhook URL with an HMAC signature.
func (d *Dispatcher) doRequest(url string, secret string, body []byte) (int, error) {
// Through a proxy the dialer only reaches the proxy, so the target's
// host is checked here instead.
if d.proxied {
if err := d.network.CheckURL(context.Background(), url); err != nil {
return 0, fmt.Errorf("%w: %v", netguard.ErrBlocked, err)
}
}
req, err := http.NewRequest(http.MethodPost, url, bytes.NewReader(body))
if err != nil {
return 0, fmt.Errorf("failed to create request: %w", err)
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("User-Agent", "Posta-Webhook/1.0")
if secret != "" {
req.Header.Set("X-Posta-Signature", "sha256="+signPayload(secret, body))
}
resp, err := d.client.Do(req)
if err != nil {
return 0, err
}
_ = resp.Body.Close()
return resp.StatusCode, nil
}
// recordDelivery persists a webhook delivery record if the delivery repo is configured.
func (d *Dispatcher) recordDelivery(userID, webhookID uint, workspaceID *uint, event string, status models.WebhookDeliveryStatus, httpStatus int, errMsg string, attempt int) {
if d.deliveryRepo == nil {
return
}
delivery := &models.WebhookDelivery{
WebhookID: webhookID,
UserID: userID,
WorkspaceID: workspaceID,
Event: event,
Status: status,
HTTPStatusCode: httpStatus,
ErrorMessage: errMsg,
Attempt: attempt,
}
if err := d.deliveryRepo.Create(delivery); err != nil {
logger.Error("failed to record webhook delivery", "error", err)
}
}