ses-dashboard 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58342ca28ca9d49b31764e988689df488d9a43061fdb145ded04a7d2dbb038b6
-  data.tar.gz: da07fcf3d2549fc68bdf24aceb72d289e3a8bf5d93238cd807932b71ef4d7cec
+  metadata.gz: 9efac9cf44528ae2052092bfcef569f312d9da609f23039459515ddc54a67072
+  data.tar.gz: 387467a34a67ec49a15241222b6a9dc077abcda5c545c872737e152b22d82905
 SHA512:
-  metadata.gz: 8757e8e5024c11d93826bdb890e46dcf6fef0bac259d43da0dbec7bd64e16f07765b01967a2d7b5bbfa75de2d11f9bf193b1949f81c937b2e450fba6b2c13092
-  data.tar.gz: b222f9246a72fd94869c85e316a69668519536e8fc973e205036ce64ea92c02dd233a6268f889dde3a871759478a1a915e6379e4bed36845c41409acf5c2d208
+  metadata.gz: 771334e8e2d8d0459d1c462022a69608958753d67845e5100bea2365fbfc9e47e1bc9f3c49e5befd804e456a5de22b3b0c23f98f6a86fe3cf4d223222eac9dbd
+  data.tar.gz: 922d8c07c25a5beac7beda1ec6bcecbb483c852f2bbe031aa65003ff181982c22a7b052c8d5e0efb5cdfda99d3339a1ccd113fc3bc4a2481dbe55ac62b656ea7

data/README.md

@@ -23,12 +23,19 @@ A mountable Rails engine that provides a real-time dashboard for Amazon SES, tra
   <tr>
     <td colspan="2" align="center"><em>Email detail with full SNS event timeline</em></td>
   </tr>
+  <tr>
+    <td colspan="2"><img src="docs/screenshots/webhook-forward-ruleset.png" alt="Webhook Forward Rules" /></td>
+  </tr>
+  <tr>
+    <td colspan="2" align="center"><em>Per-project webhook forwarding with configurable rules</em></td>
+  </tr>
 </table>
 
 ## Features
 
 - **Real-time webhook processing** -- receives SNS notifications for delivery, bounce, complaint, open, click, reject, and rendering failure events
 - **Per-project dashboards** -- stat cards, email volume charts (Chart.js), and paginated activity logs
+- **Webhook forwarding with rules** -- forward specific events to external URLs (e.g. Zapier) with a configurable rules engine; filter by event type, sender, recipient, subject, and more
 - **Pluggable authentication** -- ships with Devise, Cloudflare Zero Trust, and no-auth adapters; bring your own with any object that responds to `#authenticate(request)`
 - **CSV/JSON export** -- export filtered email activity from any project
 - **Test email sending** -- send test emails directly from the dashboard via the SES API
@@ -69,16 +76,18 @@ graph TB
             SV["SnsSignatureVerifier"]
             SA["StatsAggregator<br/>Dashboard statistics"]
             Pag["Paginatable"]
+            FR["ForwardRule<br/>field/operator/value matcher"]
         end
 
         subgraph Models
-            Project["Project<br/>name, token"]
+            Project["Project<br/>name, token, webhook_forwards"]
             Email["Email<br/>status, opens, clicks"]
             Event["EmailEvent<br/>event_type, event_data"]
         end
 
         subgraph Services
             WEP["WebhookEventPersistor"]
+            WF["WebhookForwarder<br/>rules-based HTTP forwarding"]
         end
     end
 
@@ -95,6 +104,9 @@ graph TB
     WC -->|"POST /webhook/:token"| SV
     SV --> WP
     WP --> WEP
+    WP --> WF
+    WF --> FR
+    WF -->|"HTTP POST"| ExtURL["External URL<br/>(Zapier, etc.)"]
     WEP --> Models
     Client --> SES
     SNS -->|"HTTP POST"| WC
@@ -105,6 +117,7 @@ graph TB
     style Engine fill:#f0f4ff,stroke:#3366cc
     style AWS fill:#fff3e0,stroke:#ff9800
     style Host fill:#e8f5e9,stroke:#4caf50
+    style ExtURL fill:#fce4ec,stroke:#e91e63
 ```
 
 ## Installation
@@ -251,6 +264,113 @@ Enable in production:
 c.verify_sns_signature = Rails.env.production?
 ```
 
+## Webhook Forwarding
+
+Forward SES events to external URLs (e.g. Zapier, Google Sheets, Slack) based on configurable rules. This is useful for routing bounce/complaint notifications into team workflows without consuming unnecessary webhook quota on events you don't need.
+
+![Webhook Forward Rules](docs/screenshots/webhook-forward-ruleset.png)
+
+### Per-project configuration (UI)
+
+Edit any project in the dashboard and use the **Webhook Forwards** builder to add forward targets with rules. Each target has a URL and optional rules -- all rules must match (AND logic) for the event to be forwarded. No rules means forward everything.
+
+### Per-project configuration (database)
+
+The `webhook_forwards` column on `ses_dashboard_projects` stores a JSON array:
+
+```json
+[
+  {
+    "url": "https://hooks.zapier.com/hooks/catch/123/abc/",
+    "rules": [
+      { "field": "event_type", "operator": "in", "value": ["bounce", "complaint"] }
+    ]
+  }
+]
+```
+
+### Global fallback (initializer)
+
+Used for any project that has no project-level forwards configured:
+
+```ruby
+SesDashboard.configure do |c|
+  c.webhook_forwards = [
+    { url: "https://hooks.zapier.com/hooks/catch/123/abc/",
+      rules: [{ field: "event_type", operator: "in", value: ["bounce", "complaint"] }] }
+  ]
+end
+```
+
+### Rules reference
+
+Each rule has a `field`, `operator`, and `value`. All rules on a target must match for the event to be forwarded.
+
+| Field | Type | Description |
+|---|---|---|
+| `event_type` | string | `send`, `delivery`, `bounce`, `complaint`, `open`, `click`, `reject`, `rendering_failure` |
+| `source` | string | From: email address |
+| `destination` | array | To: email addresses -- rule passes if **any** recipient matches |
+| `subject` | string | Email subject line |
+
+| Operator | Description |
+|---|---|
+| `in` | Value is included in the given array |
+| `not_in` | Value is NOT included in the given array |
+| `eq` | Exact string equality (any element for array fields) |
+| `not_eq` | String inequality |
+| `starts_with` | Prefix match (any element for array fields) |
+| `ends_with` | Suffix match (any element for array fields) |
+| `contains` | Substring match (any element for array fields) |
+
+### Forwarded payload
+
+Each matching URL receives a `POST` with a JSON body:
+
+```json
+{
+  "event_type":  "bounce",
+  "message_id":  "0102018e-abcd-1234-...",
+  "source":      "noreply@myapp.com",
+  "destination": ["user@example.com"],
+  "subject":     "Your invoice #1234",
+  "occurred_at": "2024-01-15T10:00:00Z",
+  "raw":         { "...full SES event hash..." }
+}
+```
+
+### Examples
+
+Forward only bounces and complaints to Zapier:
+
+```json
+[
+  {
+    "url": "https://hooks.zapier.com/hooks/catch/123/abc/",
+    "rules": [
+      { "field": "event_type", "operator": "in", "value": ["bounce", "complaint"] }
+    ]
+  }
+]
+```
+
+Forward bounces from a specific sender domain to one URL, all events to another:
+
+```json
+[
+  {
+    "url": "https://hooks.zapier.com/bounces",
+    "rules": [
+      { "field": "event_type", "operator": "eq", "value": "bounce" },
+      { "field": "source", "operator": "ends_with", "value": "@myapp.com" }
+    ]
+  },
+  {
+    "url": "https://example.com/all-events"
+  }
+]
+```
+
 ## Development
 
 ### Prerequisites
@@ -300,7 +420,7 @@ The engine creates three tables (prefixed `ses_dashboard_`):
 
 | Table | Key Columns |
 |---|---|
-| `ses_dashboard_projects` | `name`, `token` (unique, auto-generated), `description` |
+| `ses_dashboard_projects` | `name`, `token` (unique, auto-generated), `description`, `webhook_forwards` (JSON) |
 | `ses_dashboard_emails` | `project_id`, `message_id` (unique), `source`, `destination` (JSON), `subject`, `status`, `opens`, `clicks`, `sent_at` |
 | `ses_dashboard_email_events` | `email_id`, `event_type`, `event_data` (JSON), `occurred_at` |
 

data/app/assets/javascripts/ses_dashboard/application.js

@@ -115,6 +115,268 @@
     });
   }
 
+  // ── Webhook Forwards builder ──────────────────────────────────────────
+  var WF_FIELDS = [
+    { value: "event_type",  label: "Event Type" },
+    { value: "source",      label: "From (source)" },
+    { value: "destination", label: "To (destination)" },
+    { value: "subject",     label: "Subject" }
+  ];
+
+  var WF_OPERATORS = [
+    { value: "in",          label: "is in" },
+    { value: "not_in",      label: "is not in" },
+    { value: "eq",          label: "equals" },
+    { value: "not_eq",      label: "does not equal" },
+    { value: "starts_with", label: "starts with" },
+    { value: "ends_with",   label: "ends with" },
+    { value: "contains",    label: "contains" }
+  ];
+
+  var WF_EVENT_TYPES = [
+    "send", "delivery", "bounce", "complaint", "open", "click", "reject", "rendering_failure"
+  ];
+
+  function wfBuildSelect(options, selected, className) {
+    var sel = document.createElement("select");
+    sel.className = "form-control " + className;
+    options.forEach(function (opt) {
+      var o = document.createElement("option");
+      o.value = opt.value;
+      o.textContent = opt.label;
+      if (opt.value === selected) o.selected = true;
+      sel.appendChild(o);
+    });
+    return sel;
+  }
+
+  function wfBuildCheckboxes(selected) {
+    var wrap = document.createElement("div");
+    wrap.className = "wf-checkboxes";
+    var selectedArr = Array.isArray(selected) ? selected : [];
+    WF_EVENT_TYPES.forEach(function (et) {
+      var label = document.createElement("label");
+      label.className = "wf-checkbox-label";
+      var cb = document.createElement("input");
+      cb.type = "checkbox";
+      cb.value = et;
+      cb.className = "wf-event-cb";
+      if (selectedArr.indexOf(et) !== -1) cb.checked = true;
+      label.appendChild(cb);
+      label.appendChild(document.createTextNode(" " + et));
+      wrap.appendChild(label);
+    });
+    return wrap;
+  }
+
+  function wfBuildTextInput(value, placeholder) {
+    var input = document.createElement("input");
+    input.type = "text";
+    input.className = "form-control wf-value";
+    input.placeholder = placeholder || "";
+    input.value = value || "";
+    return input;
+  }
+
+  function wfIsArrayOperator(op) {
+    return op === "in" || op === "not_in";
+  }
+
+  function wfBuildValueInput(field, operator, value) {
+    if (field === "event_type" && wfIsArrayOperator(operator)) {
+      return wfBuildCheckboxes(value);
+    }
+    if (wfIsArrayOperator(operator)) {
+      var display = Array.isArray(value) ? value.join(", ") : (value || "");
+      return wfBuildTextInput(display, "value1, value2, value3");
+    }
+    return wfBuildTextInput(value || "", "Value");
+  }
+
+  function wfReadValue(valueContainer) {
+    // Checkboxes
+    var cbs = valueContainer.querySelectorAll(".wf-event-cb");
+    if (cbs.length > 0) {
+      var vals = [];
+      cbs.forEach(function (cb) { if (cb.checked) vals.push(cb.value); });
+      return vals;
+    }
+    // Text input
+    var input = valueContainer.querySelector(".wf-value");
+    if (input) {
+      var sel = valueContainer.closest(".wf-rule").querySelector(".wf-operator");
+      if (sel && wfIsArrayOperator(sel.value)) {
+        return input.value.split(",").map(function (s) { return s.trim(); }).filter(Boolean);
+      }
+      return input.value;
+    }
+    return "";
+  }
+
+  function wfSwapValueInput(ruleEl) {
+    var fieldSel = ruleEl.querySelector(".wf-field");
+    var opSel = ruleEl.querySelector(".wf-operator");
+    var valueWrap = ruleEl.querySelector(".wf-value-wrap");
+    var currentValue = wfReadValue(valueWrap);
+    valueWrap.innerHTML = "";
+    valueWrap.appendChild(wfBuildValueInput(fieldSel.value, opSel.value, currentValue));
+  }
+
+  function wfBuildRule(rule) {
+    rule = rule || {};
+    var field    = rule.field    || "event_type";
+    var operator = rule.operator || "in";
+    var value    = rule.value    || (wfIsArrayOperator(operator) ? [] : "");
+
+    var row = document.createElement("div");
+    row.className = "wf-rule";
+
+    var fieldSel = wfBuildSelect(WF_FIELDS, field, "wf-field");
+    var opSel    = wfBuildSelect(WF_OPERATORS, operator, "wf-operator");
+
+    var valueWrap = document.createElement("div");
+    valueWrap.className = "wf-value-wrap";
+    valueWrap.appendChild(wfBuildValueInput(field, operator, value));
+
+    var removeBtn = document.createElement("button");
+    removeBtn.type = "button";
+    removeBtn.className = "btn btn-danger btn-sm";
+    removeBtn.textContent = "\u00d7";
+    removeBtn.addEventListener("click", function () { row.remove(); });
+
+    // Swap value input when field or operator changes
+    fieldSel.addEventListener("change", function () { wfSwapValueInput(row); });
+    opSel.addEventListener("change", function () { wfSwapValueInput(row); });
+
+    row.appendChild(fieldSel);
+    row.appendChild(opSel);
+    row.appendChild(valueWrap);
+    row.appendChild(removeBtn);
+    return row;
+  }
+
+  function wfBuildTarget(target) {
+    target = target || {};
+    var card = document.createElement("div");
+    card.className = "wf-target card";
+
+    // Header
+    var header = document.createElement("div");
+    header.className = "wf-target-header";
+    var title = document.createElement("span");
+    title.className = "wf-target-title";
+    title.textContent = "Forward Target";
+    var removeBtn = document.createElement("button");
+    removeBtn.type = "button";
+    removeBtn.className = "btn btn-danger btn-sm";
+    removeBtn.textContent = "Remove";
+    removeBtn.addEventListener("click", function () { card.remove(); wfUpdateNumbers(); });
+    header.appendChild(title);
+    header.appendChild(removeBtn);
+    card.appendChild(header);
+
+    // URL
+    var urlGroup = document.createElement("div");
+    urlGroup.className = "form-group";
+    var urlLabel = document.createElement("label");
+    urlLabel.className = "form-label";
+    urlLabel.textContent = "URL";
+    var urlInput = document.createElement("input");
+    urlInput.type = "text";
+    urlInput.className = "form-control wf-url";
+    urlInput.placeholder = "https://hooks.zapier.com/hooks/catch/...";
+    urlInput.value = target.url || "";
+    urlGroup.appendChild(urlLabel);
+    urlGroup.appendChild(urlInput);
+    card.appendChild(urlGroup);
+
+    // Rules
+    var rulesLabel = document.createElement("label");
+    rulesLabel.className = "form-label";
+    rulesLabel.textContent = "Rules";
+    rulesLabel.style.marginBottom = ".25rem";
+    card.appendChild(rulesLabel);
+
+    var rulesWrap = document.createElement("div");
+    rulesWrap.className = "wf-rules";
+    var rules = target.rules || [];
+    rules.forEach(function (r) { rulesWrap.appendChild(wfBuildRule(r)); });
+    card.appendChild(rulesWrap);
+
+    var addRuleBtn = document.createElement("button");
+    addRuleBtn.type = "button";
+    addRuleBtn.className = "btn btn-outline btn-sm";
+    addRuleBtn.textContent = "+ Add Rule";
+    addRuleBtn.addEventListener("click", function () {
+      rulesWrap.appendChild(wfBuildRule());
+    });
+    card.appendChild(addRuleBtn);
+
+    return card;
+  }
+
+  function wfUpdateNumbers() {
+    var targets = document.querySelectorAll(".wf-target");
+    targets.forEach(function (t, i) {
+      t.querySelector(".wf-target-title").textContent = "Forward Target #" + (i + 1);
+    });
+  }
+
+  function wfSerialize() {
+    var targets = document.querySelectorAll(".wf-target");
+    var result = [];
+    targets.forEach(function (t) {
+      var url = t.querySelector(".wf-url").value.trim();
+      if (!url) return;
+      var rules = [];
+      t.querySelectorAll(".wf-rule").forEach(function (r) {
+        var field = r.querySelector(".wf-field").value;
+        var op    = r.querySelector(".wf-operator").value;
+        var val   = wfReadValue(r.querySelector(".wf-value-wrap"));
+        if (wfIsArrayOperator(op) && Array.isArray(val) && val.length === 0) return;
+        if (!wfIsArrayOperator(op) && val === "") return;
+        rules.push({ field: field, operator: op, value: val });
+      });
+      var entry = { url: url };
+      if (rules.length > 0) entry.rules = rules;
+      result.push(entry);
+    });
+    return result;
+  }
+
+  function initWebhookForwardsBuilder() {
+    var container = document.getElementById("wf-targets");
+    var addBtn    = document.getElementById("wf-add-target");
+    var hidden    = document.getElementById("webhook-forwards-json");
+    if (!container || !addBtn || !hidden) return;
+
+    // Load initial data
+    var dataEl = document.getElementById("wf-initial-data");
+    var initial = [];
+    if (dataEl && dataEl.textContent.trim()) {
+      try { initial = JSON.parse(dataEl.textContent); } catch (e) { /* ignore */ }
+    }
+
+    initial.forEach(function (t) {
+      container.appendChild(wfBuildTarget(t));
+    });
+    wfUpdateNumbers();
+
+    addBtn.addEventListener("click", function () {
+      container.appendChild(wfBuildTarget());
+      wfUpdateNumbers();
+    });
+
+    // Serialize to hidden field on submit
+    var form = hidden.closest("form");
+    if (form) {
+      form.addEventListener("submit", function () {
+        var data = wfSerialize();
+        hidden.value = data.length > 0 ? JSON.stringify(data) : "";
+      });
+    }
+  }
+
   // ── Boot ─────────────────────────────────────────────────────────────
   document.addEventListener("DOMContentLoaded", function () {
     initChart();
@@ -122,5 +384,6 @@
     initEventToggles();
     initFilterReset();
     initConfirmLinks();
+    initWebhookForwardsBuilder();
   });
 })();

data/app/assets/stylesheets/ses_dashboard/application.css

@@ -217,10 +217,75 @@ tr:hover td { background: var(--color-bg); }
 /* ── Token display ───────────────────────────────────────── */
 .token-display { font-family: monospace; font-size: .8125rem; background: var(--color-bg); padding: .25rem .5rem; border-radius: .25rem; border: 1px solid var(--color-border); }
 
+/* ── Webhook Forwards builder ────────────────────────────── */
+.wf-target {
+  margin-bottom: .75rem;
+  padding: 1rem;
+}
+
+.wf-target-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: .75rem;
+}
+
+.wf-target-title {
+  font-weight: 600;
+  font-size: .875rem;
+}
+
+.wf-rules {
+  display: flex;
+  flex-direction: column;
+  gap: .5rem;
+  margin-bottom: .5rem;
+}
+
+.wf-rule {
+  display: flex;
+  align-items: flex-start;
+  gap: .5rem;
+}
+
+.wf-rule .wf-field    { flex: 0 0 140px; }
+.wf-rule .wf-operator { flex: 0 0 130px; }
+.wf-rule .wf-value-wrap { flex: 1; min-width: 0; }
+.wf-rule .wf-value    { width: 100%; }
+.wf-rule .btn         { flex-shrink: 0; align-self: flex-start; margin-top: 1px; }
+
+.wf-checkboxes {
+  display: flex;
+  flex-wrap: wrap;
+  gap: .15rem .75rem;
+  padding: .4rem .25rem;
+}
+
+.wf-checkbox-label {
+  display: inline-flex;
+  align-items: center;
+  gap: .3rem;
+  font-size: .8125rem;
+  cursor: pointer;
+  white-space: nowrap;
+}
+
+.form-hint {
+  display: block;
+  font-size: .8125rem;
+  color: var(--color-text-muted);
+  margin-top: .25rem;
+}
+
+#wf-add-target { margin-top: .25rem; }
+
 /* ── Responsive ──────────────────────────────────────────── */
 @media (max-width: 640px) {
   .stat-grid { grid-template-columns: 1fr 1fr; }
   .page-header { flex-direction: column; align-items: flex-start; gap: .5rem; }
   .filter-bar { flex-direction: column; }
   .filter-bar .form-control { width: 100%; }
+  .wf-rule { flex-wrap: wrap; }
+  .wf-rule .wf-field, .wf-rule .wf-operator { flex: 1 1 45%; }
+  .wf-rule .wf-value-wrap { flex: 1 1 100%; }
 }

data/app/controllers/ses_dashboard/projects_controller.rb

@@ -55,7 +55,7 @@ module SesDashboard
     end
 
     def project_params
-      params.require(:project).permit(:name, :description)
+      params.require(:project).permit(:name, :description, :webhook_forwards_text)
     end
 
     def parse_date(str)

data/app/controllers/ses_dashboard/webhooks_controller.rb

@@ -22,6 +22,7 @@ module SesDashboard
         confirm_subscription(result.subscribe_url)
       when :process_event
         WebhookEventPersistor.new(project, result).persist
+        WebhookForwarder.new(project, result).forward
       end
 
       head :ok

data/app/models/ses_dashboard/project.rb

@@ -6,15 +6,63 @@ module SesDashboard
 
     validates :name,  presence: true
     validates :token, presence: true, uniqueness: true
+    validate  :webhook_forwards_must_be_valid_json
 
     before_validation :generate_token, on: :create
 
     scope :ordered, -> { order(:name) }
 
+    # Manual JSON serialization for the webhook_forwards column.
+    # Avoids Rails serialize API which changed between 7.0 (positional)
+    # and 8.0 (keyword-only coder:).
+    def webhook_forwards
+      raw = read_attribute(:webhook_forwards)
+      return [] if raw.blank?
+      return raw if raw.is_a?(Array)
+
+      JSON.parse(raw)
+    rescue JSON::ParserError
+      []
+    end
+
+    def webhook_forwards=(value)
+      write_attribute(:webhook_forwards, value.is_a?(String) ? value : Array(value).to_json)
+    end
+
+    # Virtual accessor for editing webhook_forwards as a JSON string in forms.
+    def webhook_forwards_text
+      forwards = Array(webhook_forwards)
+      forwards.empty? ? "" : JSON.pretty_generate(forwards)
+    end
+
+    def webhook_forwards_text=(value)
+      if value.blank?
+        self.webhook_forwards = []
+        return
+      end
+
+      parsed = JSON.parse(value)
+      self.webhook_forwards = Array(parsed)
+    rescue JSON::ParserError
+      @webhook_forwards_invalid = true
+    end
+
+    # Returns the effective forwards: project-level if configured, else global config.
+    def effective_webhook_forwards
+      project_level = Array(webhook_forwards).select { |f| (f[:url] || f["url"]).present? }
+      return project_level if project_level.any?
+
+      Array(SesDashboard.configuration&.webhook_forwards)
+    end
+
     private
 
     def generate_token
       self.token ||= SecureRandom.hex(16)
     end
+
+    def webhook_forwards_must_be_valid_json
+      errors.add(:webhook_forwards, "is not valid JSON") if @webhook_forwards_invalid
+    end
   end
 end

data/app/views/ses_dashboard/projects/_form.html.erb

@@ -19,6 +19,22 @@
     <%= f.text_area :description, class: "form-control", placeholder: "Optional description" %>
   </div>
 
+  <div class="form-group">
+    <label class="form-label">Webhook Forwards</label>
+    <small class="form-hint" style="margin-bottom:.5rem;display:block;">
+      Forward events to external URLs (e.g. Zapier). Add rules to filter which events are forwarded.
+      All rules must match. Leave empty to use global defaults.
+    </small>
+
+    <%= f.hidden_field :webhook_forwards_text, id: "webhook-forwards-json" %>
+
+    <div id="wf-targets"></div>
+
+    <button type="button" class="btn btn-outline btn-sm" id="wf-add-target">+ Add Forward Target</button>
+
+    <script type="application/json" id="wf-initial-data"><%= raw project.webhook_forwards_text.html_safe %></script>
+  </div>
+
   <%= f.submit class: "btn btn-primary" %>
   <%= link_to "Cancel", projects_path, class: "btn btn-outline" %>
 <% end %>

data/db/migrate/20240101000004_add_webhook_forwards_to_ses_dashboard_projects.rb

@@ -0,0 +1,11 @@
+_migration = begin
+  ActiveRecord::Migration["#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}"]
+rescue ArgumentError
+  ActiveRecord::Migration["#{Rails::VERSION::MAJOR}.0"]
+end
+
+class AddWebhookForwardsToSesDashboardProjects < _migration
+  def change
+    add_column :ses_dashboard_projects, :webhook_forwards, :text
+  end
+end

data/lib/ses_dashboard/forward_rule.rb

@@ -0,0 +1,72 @@
+module SesDashboard
+  # Evaluates a single forwarding rule against a WebhookProcessor::Result.
+  #
+  # A rule is a Hash with three keys:
+  #   "field"    — which Result attribute to test
+  #   "operator" — how to compare
+  #   "value"    — what to compare against
+  #
+  # Supported fields:
+  #   "event_type"  — string  ("bounce", "delivery", "complaint", …)
+  #   "source"      — string  (From: address)
+  #   "destination" — array   (To: addresses — rule passes if ANY element matches)
+  #   "subject"     — string  (email subject)
+  #
+  # Supported operators:
+  #   "in"          — field value is included in the given array
+  #   "not_in"      — field value is NOT included in the given array
+  #   "eq"          — exact string equality
+  #   "not_eq"      — string inequality
+  #   "starts_with" — prefix match (for arrays: any element matches)
+  #   "ends_with"   — suffix match (for arrays: any element matches)
+  #   "contains"    — substring match (for arrays: any element matches)
+  #
+  # New fields/operators can be added by extending the private methods below.
+  #
+  class ForwardRule
+    def initialize(rule_hash)
+      @field    = (rule_hash["field"]    || rule_hash[:field]).to_s
+      @operator = (rule_hash["operator"] || rule_hash[:operator]).to_s
+      @value    = rule_hash["value"]     || rule_hash[:value]
+    end
+
+    def match?(result)
+      field_value = extract_field(result)
+      evaluate(field_value)
+    end
+
+    private
+
+    def extract_field(result)
+      case @field
+      when "event_type"  then result.event_type
+      when "source"      then result.source
+      when "destination" then result.destination
+      when "subject"     then result.subject
+      end
+    end
+
+    def evaluate(field_value)
+      case @operator
+      when "in"          then Array(@value).include?(field_value)
+      when "not_in"      then !Array(@value).include?(field_value)
+      when "eq"          then any_string_match(field_value) { |v| v == @value.to_s }
+      when "not_eq"      then !any_string_match(field_value) { |v| v == @value.to_s }
+      when "starts_with" then any_string_match(field_value) { |v| v.start_with?(@value.to_s) }
+      when "ends_with"   then any_string_match(field_value) { |v| v.end_with?(@value.to_s) }
+      when "contains"    then any_string_match(field_value) { |v| v.include?(@value.to_s) }
+      else false
+      end
+    end
+
+    # For array fields (e.g. destination), passes if ANY element matches.
+    # For scalar fields, tests the single value.
+    def any_string_match(field_value, &block)
+      if field_value.is_a?(Array)
+        field_value.any? { |v| block.call(v.to_s) }
+      else
+        block.call(field_value.to_s)
+      end
+    end
+  end
+end

data/lib/ses_dashboard/version.rb

@@ -1,3 +1,3 @@
 module SesDashboard
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/ses_dashboard/webhook_forwarder.rb

@@ -0,0 +1,105 @@
+require "net/http"
+require "uri"
+require "json"
+
+module SesDashboard
+  # Forwards processed SES events to external webhook URLs based on configurable rules.
+  #
+  # Rules are resolved per-project (see Project#effective_webhook_forwards), with a
+  # global fallback from SesDashboard.configuration.webhook_forwards.
+  #
+  # Each forward entry supports a `rules` array — all rules must match (AND logic).
+  # If no rules are specified, every event is forwarded.
+  #
+  #   [
+  #     {
+  #       "url": "https://hooks.zapier.com/hooks/catch/abc/xyz/",
+  #       "rules": [
+  #         { "field": "event_type", "operator": "in", "value": ["bounce", "complaint"] },
+  #         { "field": "source",     "operator": "ends_with", "value": "@myapp.com" }
+  #       ]
+  #     }
+  #   ]
+  #
+  # Legacy shorthand `event_types` is still supported and auto-converted to a rule:
+  #   { "url": "...", "event_types": ["bounce"] }
+  #   ⟶ rules: [{ field: "event_type", operator: "in", value: ["bounce"] }]
+  #
+  class WebhookForwarder
+    OPEN_TIMEOUT = 5  # seconds
+    READ_TIMEOUT = 10 # seconds
+
+    def initialize(project, result)
+      @project = project
+      @result  = result
+    end
+
+    def forward
+      forwards = @project.effective_webhook_forwards
+      return if forwards.empty?
+
+      forwards.each do |config|
+        url = config[:url] || config["url"]
+        next if url.blank?
+        next unless matches_rules?(config)
+
+        post_to(url)
+      rescue => e
+        log_warn("Forward to #{url} failed: #{e.message}")
+      end
+    end
+
+    private
+
+    def matches_rules?(config)
+      rules = resolve_rules(config)
+      return true if rules.empty?
+
+      rules.all? { |rule| ForwardRule.new(rule).match?(@result) }
+    end
+
+    # Supports both the new `rules` format and the legacy `event_types` shorthand.
+    def resolve_rules(config)
+      rules = Array(config["rules"] || config[:rules])
+      return rules if rules.any?
+
+      event_types = Array(config["event_types"] || config[:event_types])
+      return [] if event_types.empty?
+
+      [{ "field" => "event_type", "operator" => "in", "value" => event_types }]
+    end
+
+    def post_to(url)
+      uri  = URI(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl      = uri.scheme == "https"
+      http.open_timeout = OPEN_TIMEOUT
+      http.read_timeout = READ_TIMEOUT
+
+      req                  = Net::HTTP::Post.new(uri.request_uri)
+      req["Content-Type"]  = "application/json"
+      req.body             = build_payload
+
+      response = http.request(req)
+      unless response.is_a?(Net::HTTPSuccess)
+        log_warn("Forward to #{url} returned HTTP #{response.code}")
+      end
+    end
+
+    def build_payload
+      {
+        event_type:  @result.event_type,
+        message_id:  @result.message_id,
+        source:      @result.source,
+        destination: @result.destination,
+        subject:     @result.subject,
+        occurred_at: @result.occurred_at&.iso8601,
+        raw:         @result.raw_payload
+      }.to_json
+    end
+
+    def log_warn(msg)
+      Rails.logger.warn("[SesDashboard] #{msg}") if defined?(Rails)
+    end
+  end
+end

data/lib/ses_dashboard.rb

@@ -37,6 +37,15 @@ module SesDashboard
     attr_accessor :cloudflare_team_domain  # e.g. "myteam.cloudflareaccess.com"
     attr_accessor :cloudflare_aud          # JWT audience (your CF application AUD)
 
+    # Webhook forwarding — forward specific event types to external URLs (e.g. Zapier)
+    # Format: array of hashes with :url and :event_types keys
+    # Example:
+    #   c.webhook_forwards = [
+    #     { url: "https://hooks.zapier.com/...", event_types: ["bounce", "complaint"] }
+    #   ]
+    # Omit :event_types (or set to []) to forward all event types.
+    attr_accessor :webhook_forwards
+
     def initialize
       @aws_region              = ENV.fetch("AWS_REGION", "us-east-1")
       @aws_access_key_id       = nil
@@ -50,6 +59,7 @@ module SesDashboard
       @verify_sns_signature    = false
       @cloudflare_team_domain  = nil
       @cloudflare_aud          = nil
+      @webhook_forwards        = []
     end
   end
 end
@@ -57,6 +67,8 @@ end
 require_relative "ses_dashboard/version"
 require_relative "ses_dashboard/client"
 require_relative "ses_dashboard/webhook_processor"
+require_relative "ses_dashboard/forward_rule"
+require_relative "ses_dashboard/webhook_forwarder"
 require_relative "ses_dashboard/sns_signature_verifier"
 require_relative "ses_dashboard/stats_aggregator"
 require_relative "ses_dashboard/paginatable"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ses-dashboard
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - antodoms
@@ -331,6 +331,7 @@ files:
 - db/migrate/20240101000001_create_ses_dashboard_projects.rb
 - db/migrate/20240101000002_create_ses_dashboard_emails.rb
 - db/migrate/20240101000003_create_ses_dashboard_email_events.rb
+- db/migrate/20240101000004_add_webhook_forwards_to_ses_dashboard_projects.rb
 - docker-compose.yml
 - lib/ses/dashboard.rb
 - lib/ses_dashboard.rb
@@ -339,10 +340,12 @@ files:
 - lib/ses_dashboard/auth/devise_adapter.rb
 - lib/ses_dashboard/client.rb
 - lib/ses_dashboard/engine.rb
+- lib/ses_dashboard/forward_rule.rb
 - lib/ses_dashboard/paginatable.rb
 - lib/ses_dashboard/sns_signature_verifier.rb
 - lib/ses_dashboard/stats_aggregator.rb
 - lib/ses_dashboard/version.rb
+- lib/ses_dashboard/webhook_forwarder.rb
 - lib/ses_dashboard/webhook_processor.rb
 homepage: https://github.com/antodoms/ses_dashboard
 licenses: