Skip to content

armgit / posta

Public Imported from GitHub
0

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.

fix(webhooks): scope dispatch to workspace and add campaign events

Jonas Kaninda99fae79d6b47
diff --git a/docs/docs/webhooks/event-types.md b/docs/docs/webhooks/event-types.md
index daa96fc..10ae3ee 100644
--- a/docs/docs/webhooks/event-types.md
+++ b/docs/docs/webhooks/event-types.md
@@ -14,7 +14,14 @@ Subscribe to these events when creating webhooks:
|-------|-------------|
| `email.sent` | Email was successfully delivered to the SMTP server |
| `email.failed` | Email delivery failed after all retries |
-| `email.bounced` | Email bounced (hard or soft bounce) |
+| `email.inbound` | An inbound message was received and forwarded |
+
+## Campaign Events
+
+| Event | Description |
+|-------|-------------|
+| `campaign.started` | A campaign began sending |
+| `campaign.completed` | A campaign finished sending all messages |
## Event Payload Structure
@@ -68,18 +75,28 @@ Fired when delivery fails after all retries:
}
```
-### `email.bounced`
+### `campaign.started`
-Fired when an email bounces:
+Fired when a campaign begins sending:
```json
{
- "event": "email.bounced",
- "data": {
- "email_id": "uuid",
- "bounce_type": "hard",
- "message": "Mailbox not found"
- }
+ "event": "campaign.started",
+ "campaign_id": 42,
+ "name": "Spring Newsletter",
+ "timestamp": "2026-01-01T00:00:01Z"
+}
+```
+
+### `campaign.completed`
+
+Fired when a campaign finishes sending all of its messages:
+
+```json
+{
+ "event": "campaign.completed",
+ "campaign_id": 42,
+ "name": "Spring Newsletter",
+ "timestamp": "2026-01-01T00:00:01Z"
}
```
diff --git a/docs/docs/webhooks/overview.md b/docs/docs/webhooks/overview.md
index ac7516f..80fb113 100644
--- a/docs/docs/webhooks/overview.md
+++ b/docs/docs/webhooks/overview.md
@@ -19,7 +19,7 @@ Create a webhook from the dashboard or via `POST /api/v1/users/me/webhooks`:
```json
{
"url": "https://your-app.com/webhooks/posta",
- "events": ["email.sent", "email.failed", "email.bounced"],
+ "events": ["email.sent", "email.failed", "campaign.completed"],
"secret": "your-webhook-secret"
}
```
diff --git a/go.mod b/go.mod
index cef7a5b..8fcae60 100644
--- a/go.mod
+++ b/go.mod
@@ -13,7 +13,7 @@ require (
github.com/hibiken/asynq v0.26.0
github.com/jkaninda/go-utils v0.1.4
github.com/jkaninda/logger v0.0.5
- github.com/jkaninda/okapi v0.6.0
+ github.com/jkaninda/okapi v0.6.1
github.com/joho/godotenv v1.5.1
github.com/lib/pq v1.12.3
github.com/pquerna/otp v1.5.0
diff --git a/go.sum b/go.sum
index 715ff11..cffdec3 100644
--- a/go.sum
+++ b/go.sum
@@ -103,8 +103,8 @@ github.com/jkaninda/go-utils v0.1.4 h1:ZdNlI+yLWc4/S0qKcCNQIPj+6lHSdJcGaxtRADAif
github.com/jkaninda/go-utils v0.1.4/go.mod h1:Aa54jEAcDykc3CnOdreqZG80UfSZOvrYecyusu+oPb4=
github.com/jkaninda/logger v0.0.5 h1:fTHKgDsHtuN8rkSBvwe6QStfi8yIdm8O3r0g99dRDTY=
github.com/jkaninda/logger v0.0.5/go.mod h1:ZUXJ2BdxDPG6e8t6mbKhc2ZFaFi2Iuy/4ukquFrPkFE=
-github.com/jkaninda/okapi v0.6.0 h1:KsUNTPwYg/rlfgBc//dwCbo0bUpxPCndMwayvf9gqkY=
-github.com/jkaninda/okapi v0.6.0/go.mod h1:cEDp7ZxdjNQvveW3Oc0PfMjseT30EMN1H9Y93mTJvgU=
+github.com/jkaninda/okapi v0.6.1 h1:eJA65U0hrFrdQzesEoXa2o6FNrJJuo9qupymZFpcRhE=
+github.com/jkaninda/okapi v0.6.1/go.mod h1:cEDp7ZxdjNQvveW3Oc0PfMjseT30EMN1H9Y93mTJvgU=
github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0=
github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4=
github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY=
diff --git a/internal/handlers/webhook_handler.go b/internal/handlers/webhook_handler.go
index f283c84..6e2464f 100644
--- a/internal/handlers/webhook_handler.go
+++ b/internal/handlers/webhook_handler.go
@@ -33,8 +33,8 @@ type WebhookHandler struct {
}
type CreateWebhookRequest struct {
Body struct {
- URL string `json:"url" required:"true" format:"uri"`
- Events []string `json:"events" required:"true" minItems:"1"`
+ URL string `json:"url" required:"true" format:"url"`
+ Events []string `json:"events" required:"true" minItems:"1" enum:"email.sent,email.failed,email.inbound,campaign.started,campaign.completed"`
Filters []string `json:"filters"`
} `json:"body"`
}
@@ -52,14 +52,6 @@ func (h *WebhookHandler) Create(c *okapi.Context, req *CreateWebhookRequest) err
}
scope := getScope(c)
- // Validate event names
- validEvents := map[string]bool{"email.sent": true, "email.failed": true, "email.inbound": true}
- for _, event := range req.Body.Events {
- if !validEvents[event] {
- return c.AbortBadRequest("invalid event: " + event + ". Valid events: email.sent, email.failed, email.inbound")
- }
- }
-
// Generate a random signing secret for HMAC webhook signatures
secretBytes := make([]byte, 32)
if _, err := rand.Read(secretBytes); err != nil {
diff --git a/internal/services/webhook/dispatcher.go b/internal/services/webhook/dispatcher.go
index 1dfc4f8..f371547 100644
--- a/internal/services/webhook/dispatcher.go
+++ b/internal/services/webhook/dispatcher.go
@@ -155,6 +155,15 @@ type Payload struct {
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
@@ -175,6 +184,26 @@ func (d *Dispatcher) Dispatch(userID uint, workspaceID *uint, event string, emai
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.
diff --git a/internal/worker/campaign_processor.go b/internal/worker/campaign_processor.go
index 9ccfc20..a1f582c 100644
--- a/internal/worker/campaign_processor.go
+++ b/internal/worker/campaign_processor.go
@@ -206,7 +206,7 @@ func (p *CampaignProcessor) HandleCampaignStart(_ context.Context, t *asynq.Task
return err
}
if p.dispatcher != nil {
- p.dispatcher.Dispatch(campaign.UserID, campaign.WorkspaceID, "campaign.started", fmt.Sprint(campaign.ID), campaign.FromEmail)
+ p.dispatcher.DispatchCampaign(campaign.UserID, campaign.WorkspaceID, "campaign.started", campaign.ID, campaign.Name, campaign.FromEmail)
}
return nil
}
@@ -242,7 +242,7 @@ func (p *CampaignProcessor) HandleCampaignBatch(_ context.Context, t *asynq.Task
return err
}
if p.dispatcher != nil {
- p.dispatcher.Dispatch(campaign.UserID, campaign.WorkspaceID, "campaign.completed", fmt.Sprint(campaign.ID), campaign.FromEmail)
+ p.dispatcher.DispatchCampaign(campaign.UserID, campaign.WorkspaceID, "campaign.completed", campaign.ID, campaign.Name, campaign.FromEmail)
}
return nil
}
@@ -379,7 +379,7 @@ func (p *CampaignProcessor) HandleCampaignBatch(_ context.Context, t *asynq.Task
return err
}
if p.dispatcher != nil {
- p.dispatcher.Dispatch(campaign.UserID, campaign.WorkspaceID, "campaign.completed", fmt.Sprint(campaign.ID), campaign.FromEmail)
+ p.dispatcher.DispatchCampaign(campaign.UserID, campaign.WorkspaceID, "campaign.completed", campaign.ID, campaign.Name, campaign.FromEmail)
}
return nil
}
diff --git a/web/src/views/webhooks/Webhooks.vue b/web/src/views/webhooks/Webhooks.vue
index d86b56b..dfc25e9 100644
--- a/web/src/views/webhooks/Webhooks.vue
+++ b/web/src/views/webhooks/Webhooks.vue
@@ -29,7 +29,7 @@ const createdWebhook = ref<Webhook | null>(null)
const showSecretModal = ref(false)
const copied = ref(false)
-const availableEvents = ['email.sent', 'email.failed', 'email.inbound']
+const availableEvents = ['email.sent', 'email.failed', 'email.inbound', 'campaign.started', 'campaign.completed']
const { pageable, goToPage } = usePagination(async (page) => {
loading.value = true