angarium 0.1.0

data/app/models/angarium/delivery.rb

@@ -0,0 +1,254 @@
+require "uri"
+
+module Angarium
+  class Delivery < ApplicationRecord
+    # Delivery lifecycle. Terminal: succeeded, exhausted, blocked (SSRF),
+    # gone (410), canceled (endpoint no longer accepting deliveries at attempt time).
+    enum :state, {
+      pending: "pending", delivering: "delivering", succeeded: "succeeded",
+      exhausted: "exhausted", blocked: "blocked", gone: "gone", canceled: "canceled"
+    }, default: :pending
+
+    belongs_to :event, class_name: "Angarium::Event"
+    belongs_to :endpoint, class_name: "Angarium::Endpoint"
+    has_many :delivery_attempts, class_name: "Angarium::DeliveryAttempt", dependent: :destroy
+
+    # Transient: set on a delivery built for a manual, forced send (e.g.
+    # endpoint.ping!(force: true)) so its first attempt bypasses the endpoint
+    # status guard. Not persisted; only the enqueued job carries it forward.
+    attr_accessor :force_send
+
+    after_create_commit { force_send ? DeliverJob.perform_later(id, true) : DeliverJob.perform_later(id) }
+
+    # Recover deliveries stranded in "delivering": a worker set the state to
+    # "delivering" (in #deliver!) but died (crash, deploy, OOM) before
+    # recording the attempt or rescheduling, so the job's `pending?` guard never
+    # re-runs it. Anything still "delivering" whose last attempt started before
+    # `older_than.ago` is presumed abandoned and reset to "pending" + re-enqueued.
+    # Returns the number requeued. Keep `older_than` well above a single attempt's
+    # worst-case duration (open_timeout + http_timeout) so a live-but-slow worker
+    # isn't reaped; a redelivery is at-least-once-safe regardless.
+    def self.reap_stalled(older_than: Angarium.config.delivering_timeout)
+      return 0 unless older_than
+
+      ids = where(state: "delivering").where(last_attempt_at: ..older_than.ago).pluck(:id)
+      return 0 if ids.empty?
+
+      where(id: ids).update_all(state: "pending", next_attempt_at: Time.current, updated_at: Time.current)
+      ids.each { |id| DeliverJob.perform_later(id) }
+      ids.size
+    end
+
+    # Performs one attempt. Records a DeliveryAttempt, then transitions to
+    # succeeded, blocked (SSRF), schedules a retry, or exhausts. Returns the attempt.
+    def deliver!(client: Client.new, force: false)
+      payload = {delivery_id: id, endpoint_id: endpoint_id, event: event.name, force: force}
+      ActiveSupport::Notifications.instrument("deliver.angarium", payload) do
+        # An endpoint's status can change after a delivery is queued: auto-disable
+        # partway through a retry cycle, an operator pause!, or a 410 from a sibling
+        # delivery. The dispatch-time `enabled` filter only gates delivery creation,
+        # not queued retries, so re-check here before attempting. `force: true`
+        # (a manual ping!/redeliver!) overrides the guard for this one attempt, so
+        # you can test an endpoint before re-enabling it; any retry it schedules
+        # follows the normal status rules again.
+        unless force
+          if endpoint.paused?
+            payload[:outcome] = :held
+            return hold_for_pause!
+          end
+          unless endpoint.enabled?
+            payload[:outcome] = :canceled
+            return cancel!(reason: endpoint.status)
+          end
+        end
+
+        update!(state: "delivering", attempt_count: attempt_count + 1, last_attempt_at: Time.current)
+        payload[:attempt] = attempt_count
+
+        # Re-resolve at delivery time (rather than trusting the save-time check)
+        # to catch DNS rebinding: a host that now resolves to a private/disallowed
+        # IP is blocked even if it was fine when the endpoint was saved. Any
+        # disallowed resolved address is a terminal block.
+        addresses = AddressPolicy.resolve(destination_host)
+
+        if addresses.any? { |ip| !AddressPolicy.ip_allowed?(ip, endpoint) }
+          payload[:outcome] = :blocked
+          payload[:error] = "blocked: destination address not permitted"
+          attempt = delivery_attempts.create!(error: payload[:error])
+          update!(state: "blocked", next_attempt_at: nil)
+          endpoint.record_delivery_failure!
+          return attempt
+        end
+
+        # Fail closed: our resolver is the single source of truth. If we can't
+        # resolve the host, do NOT let HTTPX resolve it unvalidated; record a
+        # retryable failure. A transient DNS blip is retried; a persistently
+        # unresolvable host eventually exhausts.
+        if addresses.empty?
+          payload[:outcome] = :unresolvable
+          payload[:error] = "unresolvable host: #{destination_host}"
+          attempt = delivery_attempts.create!(error: payload[:error])
+          handle_failure!
+          return attempt
+        end
+
+        body = request_body
+        ts = Time.now.to_i
+        webhook_id = id.to_s
+        signature = Signature.sign(payload: body, id: webhook_id, timestamp: ts, secret: endpoint.active_signing_secrets)
+        headers = (endpoint.custom_headers || {}).merge(
+          "webhook-id" => webhook_id,
+          "webhook-timestamp" => ts.to_s,
+          "webhook-signature" => signature
+        )
+        result = client.post(
+          endpoint.url,
+          body: body,
+          headers: headers,
+          # Pin the connection to exactly the IP(s) we just validated, so HTTPX
+          # can't re-resolve and connect somewhere else after our check (the
+          # rebinding window). TLS SNI/cert verification still uses the URL's
+          # host. `addresses` is guaranteed non-empty here (the fail-closed
+          # branch above returned early otherwise), so the connection always pins.
+          addresses: addresses.map(&:to_s)
+        )
+
+        attempt = delivery_attempts.create!(
+          response_code: result.code,
+          response_body: result.body,
+          error: result.error,
+          duration: result.duration
+        )
+        payload[:code] = result.code
+        payload[:http_duration] = result.duration
+        payload[:error] = result.error
+
+        # Status handling follows the Standard Webhooks receiver-etiquette guidance:
+        #   2xx           -> success
+        #   410 Gone      -> the receiver wants no more webhooks: disable + stop (terminal)
+        #   everything else (3xx, 429, 5xx, ...) -> retryable failure. 429/502/504
+        #     ("throttle" codes) are retried with backoff and honor Retry-After.
+        if result.success?
+          payload[:outcome] = :delivered
+          succeed!
+        elsif result.code == 410
+          payload[:outcome] = :gone
+          handle_gone!
+        else
+          payload[:outcome] = :failed
+          handle_failure!(retry_after: retry_after_seconds(result.headers))
+        end
+        attempt
+      end
+    end
+
+    # Reset the retry cycle and re-enqueue immediately. Keeps prior
+    # DeliveryAttempt history. `force: true` sends even if the endpoint is no
+    # longer enabled (for the re-enqueued attempt). Returns self.
+    def redeliver!(force: false)
+      update!(state: "pending", next_attempt_at: nil, attempt_count: 0)
+      force ? DeliverJob.perform_later(id, true) : DeliverJob.perform_later(id)
+      self
+    end
+
+    private
+
+    # Endpoint was paused after this delivery was queued. Park it (no attempt
+    # consumed, no failure recorded) by clearing the schedule and leaving it
+    # pending; Endpoint#enable! re-enqueues parked deliveries so a pause/resume
+    # cycle doesn't lose them. Returns nil (no attempt was made).
+    def hold_for_pause!
+      update!(state: "pending", next_attempt_at: nil)
+      nil
+    end
+
+    # Endpoint reached a terminal state (disabled or gone) after this delivery was
+    # queued. Stop retrying and log why. Recover with redeliver! if the endpoint is
+    # later re-enabled. Returns the logged attempt.
+    def cancel!(reason:)
+      attempt = delivery_attempts.create!(error: "canceled: endpoint #{reason}")
+      update!(state: "canceled", next_attempt_at: nil)
+      attempt
+    end
+
+    def succeed!
+      update!(state: "succeeded", next_attempt_at: nil)
+      endpoint.record_delivery_success!
+      # A successful delivery to an unverified endpoint (a forced ping!) proves it
+      # can receive webhooks, so verify it. No-op for any other status.
+      endpoint.verify!
+    end
+
+    # HTTP 410 Gone: the receiver is explicitly done with this endpoint. Per the
+    # Standard Webhooks guidance, disable the endpoint (no further deliveries) and
+    # mark this delivery terminal, with no retries.
+    def handle_gone!
+      update!(state: "gone", next_attempt_at: nil)
+      endpoint.deactivate!(reason: :gone)
+    end
+
+    def handle_failure!(retry_after: nil)
+      schedule = Array(Angarium.config.retry_schedule)
+      base = schedule[attempt_count - 1] # attempt_count already incremented for this attempt
+
+      if base.nil?
+        update!(state: "exhausted")
+        endpoint.record_delivery_failure!
+        Angarium.notify(:on_delivery_exhausted, self)
+      else
+        wait = jittered(base)
+        # Honor Retry-After only when it asks us to wait LONGER than our own
+        # backoff: take the later of the two. A receiver must never be able to
+        # pull retries EARLIER than our schedule; otherwise a malicious or
+        # misconfigured receiver could send a tiny Retry-After to defeat our
+        # backoff and make us hammer it. Retry-After can delay, never expedite.
+        wait = [wait, retry_after].max if retry_after
+        update!(state: "pending", next_attempt_at: Time.current + wait)
+        DeliverJob.set(wait: wait).perform_later(id)
+      end
+    end
+
+    # Additive positive jitter to spread retries and avoid thundering herds.
+    def jittered(base)
+      base + (rand * base.to_f * Angarium.config.retry_jitter)
+    end
+
+    # Honor a receiver's Retry-After header (seconds or an HTTP-date), capped by
+    # config.max_retry_after. Returns nil when disabled, absent, or invalid.
+    def retry_after_seconds(headers)
+      return nil unless Angarium.config.respect_retry_after && headers.present?
+
+      value = headers["retry-after"]
+      return nil unless value
+
+      seconds =
+        if value.match?(/\A\d+\z/)
+          value.to_i
+        else
+          begin
+            Time.httpdate(value) - Time.now
+          rescue ArgumentError
+            nil
+          end
+        end
+
+      return nil if seconds.nil? || seconds.negative?
+
+      cap = Angarium.config.max_retry_after
+      cap ? [seconds, cap].min : seconds
+    end
+
+    def destination_host
+      URI.parse(endpoint.url).host
+    end
+
+    def request_body
+      {
+        id: id,
+        event: event.name,
+        created_at: created_at.iso8601,
+        data: event.payload
+      }.to_json
+    end
+  end
+end

data/app/models/angarium/delivery_attempt.rb

@@ -0,0 +1,14 @@
+module Angarium
+  class DeliveryAttempt < ApplicationRecord
+    belongs_to :delivery, class_name: "Angarium::Delivery"
+
+    # Delete delivery attempts older than the cutoff. `older_than` may be a
+    # duration (e.g. 90.days) or an absolute Time. Returns the number deleted.
+    # (A Time also responds to #ago but requires an argument, so branch on the
+    # type rather than duck-typing #ago.)
+    def self.prune(older_than:)
+      cutoff = older_than.is_a?(ActiveSupport::Duration) ? older_than.ago : older_than
+      where(created_at: ...cutoff).delete_all
+    end
+  end
+end

data/app/models/angarium/endpoint.rb

@@ -0,0 +1,217 @@
+require "securerandom"
+require "base64"
+
+module Angarium
+  class Endpoint < ApplicationRecord
+    # Headers a user-supplied custom header may never set: the Standard Webhooks
+    # signature headers (which must not be spoofable) and transport/hop-by-hop
+    # headers whose override invites request smuggling or receiver confusion.
+    RESERVED_HEADERS = %w[
+      webhook-id webhook-timestamp webhook-signature
+      host content-length content-type transfer-encoding connection
+    ].freeze
+
+    belongs_to :owner, polymorphic: true
+    has_many :deliveries, class_name: "Angarium::Delivery", dependent: :destroy
+
+    # Encrypted at rest: the signing secret(s) and custom_headers; the latter
+    # commonly carries a receiver credential (e.g. an Authorization bearer token),
+    # so it gets the same protection as the signing secret.
+    encrypts :signing_secret, :previous_signing_secret
+    encrypts :custom_headers
+
+    # Lifecycle status. `enabled` endpoints receive deliveries; the rest don't.
+    #   unverified: created but not yet proven; verified by a successful delivery
+    #               (a forced #ping!) or #verify!, which moves it to `enabled`
+    #   paused:     turned off manually (resumable via #enable!)
+    #   disabled:   auto-disabled after too many consecutive failures (resumable)
+    #   gone:       the receiver returned HTTP 410; treat as terminal
+    enum :status, {enabled: "enabled", paused: "paused", disabled: "disabled", gone: "gone", unverified: "unverified"},
+      default: :enabled
+
+    # Rails < 8.1's SQLite adapter doesn't parse the `DEFAULT FALSE` literal
+    # SQLite reports back for boolean columns (fixed in
+    # ActiveRecord::ConnectionAdapters::SQLite3::SchemaStatements
+    # #extract_value_from_default starting in Rails 8.1), leaving this attribute
+    # nil on a new record instead of the schema default. Declaring the default
+    # here keeps behavior correct on every supported Rails version.
+    attribute :allow_private_network, :boolean, default: false
+
+    before_validation :ensure_signing_secret, on: :create
+
+    validates :name, presence: true
+    validates :url, presence: true
+    validates :url, "angarium/endpoint_url": true, if: :verify_url_address?
+    validate :allowed_networks_are_valid_cidrs
+    validate :custom_headers_are_strings
+
+    def self.generate_signing_secret
+      "whsec_#{Base64.strict_encode64(SecureRandom.bytes(32))}"
+    end
+
+    def subscribed_to?(event_name)
+      Array(subscribed_events).any? { |pattern| EventMatcher.match?(pattern, event_name) }
+    end
+
+    # Secrets a receiver may currently hold: always the active secret, plus the
+    # previous one while it's still within the rotation grace window. Deliveries
+    # sign with every returned secret so receivers can roll over with zero
+    # downtime.
+    def active_signing_secrets
+      secrets = [signing_secret]
+      if previous_signing_secret.present? && secret_rotated_at.present? &&
+          secret_rotated_at > Angarium.config.signing_secret_grace_period.ago
+        secrets << previous_signing_secret
+      end
+      secrets
+    end
+
+    # Rotate the signing secret and persist. Returns the new plaintext secret.
+    # The previous secret stays valid for `config.signing_secret_grace_period`
+    # (deliveries are signed with both during that window), so receivers can
+    # roll over to the new secret with zero downtime.
+    def rotate_secret!
+      update!(
+        previous_signing_secret: signing_secret,
+        signing_secret: self.class.generate_signing_secret,
+        secret_rotated_at: Time.current
+      )
+      signing_secret
+    end
+
+    def record_delivery_success!
+      # Reset from the database, not this (possibly stale) in-memory copy: a
+      # concurrent failed delivery may have raised the counter since we loaded.
+      # The WHERE skips a write when it is already zero.
+      self.class.where(id: id).where.not(consecutive_failures: 0).update_all(consecutive_failures: 0)
+      self.consecutive_failures = 0
+    end
+
+    def record_delivery_failure!
+      # Atomic increment. Without it, concurrent deliveries to the same endpoint
+      # each read a stale counter and lose increments (last write wins), so
+      # auto-disable would undercount. Reload to read the true post-increment
+      # count before deciding whether to disable.
+      self.class.update_counters(id, consecutive_failures: 1)
+      reload
+
+      threshold = Angarium.config.auto_disable_endpoint_after
+      deactivate!(reason: :consecutive_failures) if threshold && consecutive_failures >= threshold
+    end
+
+    # Move to a non-delivering state (no further deliveries) and fire the
+    # on_endpoint_deactivated callback once. `reason` maps to the target status:
+    #   :consecutive_failures -> disabled (auto-disable, only from `enabled`)
+    #   :gone                 -> gone     (receiver returned HTTP 410; overrides
+    #                                       any non-gone status, so a racing
+    #                                       auto-disable can't clobber a 410)
+    def deactivate!(reason:)
+      target, from = (reason == :gone) ? [:gone, nil] : [:disabled, :enabled]
+      transition_status!(target, from: from) { Angarium.notify(:on_endpoint_deactivated, self, reason) }
+    end
+
+    # Pause deliveries manually. Resumable via #enable!.
+    def pause!
+      transition_status!(:paused)
+    end
+
+    # (Re-)enable deliveries and clear the failure counter. Works from any state,
+    # including `gone` (an explicit operator override of a receiver's 410).
+    def enable!
+      return false unless transition_status!(:enabled, consecutive_failures: 0)
+      # Resume deliveries parked while this endpoint was paused (pending with no
+      # scheduled attempt). Dispatch creates none while paused, so this only
+      # re-enqueues the held ones.
+      deliveries.where(state: "pending", next_attempt_at: nil).find_each { |d| DeliverJob.perform_later(d.id) }
+      true
+    end
+
+    # Promote an `unverified` endpoint to `enabled` once it has proven it can
+    # receive webhooks. A no-op on any other status: a `disabled`/`gone` endpoint
+    # is revived with #enable!, not verified. Called automatically when a delivery
+    # to an unverified endpoint succeeds (a forced #ping!), or manually. Fires
+    # on_endpoint_verified exactly once, even under concurrent verification.
+    def verify!
+      transition_status!(:enabled, from: :unverified) { Angarium.notify(:on_endpoint_verified, self) }
+    end
+
+    # Deliver a synthetic `angarium.ping` event to this endpoint, bypassing
+    # subscription matching (a ping is always sent). By default a ping also
+    # ignores the endpoint's status, so you can test an endpoint that is paused,
+    # disabled, or not yet enabled; pass `force: false` to respect the status
+    # guard instead. Returns the created Angarium::Delivery, whose
+    # after_create_commit enqueues the DeliverJob; reload it to inspect the outcome.
+    def ping!(payload = {message: "Angarium ping"}, force: true)
+      event = Angarium::Event.create!(name: "angarium.ping", payload: payload)
+      deliveries.create!(event: event) { |d| d.force_send = force }
+    end
+
+    private
+
+    # Atomically move to `target` status, stamping status_changed_at (and any
+    # `extra` columns) only on a real change, so a no-op transition writes nothing.
+    # With `from:` the change applies only from those source statuses; otherwise
+    # from any status but the target. Returns true iff this call made the change,
+    # so a caller's block runs exactly once even under concurrent transitions (no
+    # double callback). All status transitions go through here to stay consistent.
+    def transition_status!(target, from: nil, **extra)
+      target = target.to_s
+      from &&= Array(from).map(&:to_s)
+      # Two independent guards, both always applied: skip if we're already at the
+      # target (no redundant write / no spurious callback), and skip if we're not
+      # in a permitted source status. The atomic update enforces both at the DB
+      # level, so a concurrent transition can't slip past either.
+      return false if status == target || from&.exclude?(status)
+
+      scope = self.class.where(id: id).where.not(status: target)
+      scope = scope.where(status: from) if from
+      changed = scope.update_all({status: target, status_changed_at: Time.current, updated_at: Time.current}.merge(extra))
+      return false if changed.zero?
+
+      reload
+      yield if block_given?
+      true
+    end
+
+    def ensure_signing_secret
+      self.signing_secret ||= self.class.generate_signing_secret
+    end
+
+    # Re-run the URL + SSRF address check only when something that affects the
+    # decision changes: the URL itself, or the SSRF controls (allow_private_network,
+    # allowed_networks). This avoids a DNS lookup on unrelated updates (e.g.
+    # toggling `active`), while still catching a URL that a tightened policy now
+    # disallows. (Reassign allowed_networks to a new array to trigger dirty
+    # tracking; in-place mutation isn't detected.)
+    def verify_url_address?
+      return false if url.blank?
+
+      new_record? ||
+        will_save_change_to_url? ||
+        will_save_change_to_allow_private_network? ||
+        will_save_change_to_allowed_networks?
+    end
+
+    def allowed_networks_are_valid_cidrs
+      Array(allowed_networks).reject(&:blank?).each do |cidr|
+        IPAddr.new(cidr.to_s)
+      rescue IPAddr::InvalidAddressError
+        errors.add(:allowed_networks, "contains an invalid CIDR: #{cidr}")
+      end
+    end
+
+    def custom_headers_are_strings
+      return if custom_headers.blank?
+
+      unless custom_headers.is_a?(Hash) &&
+          custom_headers.all? { |k, v| k.is_a?(String) && v.is_a?(String) }
+        errors.add(:custom_headers, "must be a hash of string keys and values")
+        return
+      end
+
+      if custom_headers.keys.any? { |k| RESERVED_HEADERS.include?(k.downcase) }
+        errors.add(:custom_headers, "cannot override reserved or transport headers (#{RESERVED_HEADERS.join(", ")})")
+      end
+    end
+  end
+end

data/app/models/angarium/event.rb

@@ -0,0 +1,7 @@
+module Angarium
+  class Event < ApplicationRecord
+    has_many :deliveries, class_name: "Angarium::Delivery", dependent: :destroy
+
+    validates :name, presence: true
+  end
+end

data/app/policies/angarium/api/policy.rb

@@ -0,0 +1,78 @@
+module Angarium
+  module Api
+    # The single place for API authorization:
+    #   #scope(relation)  narrows a base relation to what this user may see
+    #   #owner            who a newly-created endpoint belongs to
+    #   #<action>?        whether each action is allowed
+    #
+    # Angarium instantiates config.policy_class per request with the controller
+    # and (for member actions) the target record, and runs it in the controller's
+    # context, so `current_user`, `params`, and `controller` are available.
+    #
+    # Defaults are permissive and single-owner: you see and create your own
+    # endpoints and may do anything to them. Subclass and override to change the
+    # scope, support multi-tenancy or admin-on-behalf-of, or restrict actions.
+    class Policy
+      attr_reader :controller, :record
+
+      def initialize(controller, record = nil)
+        @controller = controller
+        @record = record
+      end
+
+      def current_user = controller.angarium_current_user
+      def params = controller.params
+
+      # Narrow the given base relation to the endpoints this user may see and act
+      # on (reads and finds go through this; deliveries and attempts scope through
+      # their endpoint). Receives a relation so you can compose on top of it.
+      def scope(relation)
+        relation.where(owner: current_user)
+      end
+
+      # Owner assigned to a newly-created endpoint. Override to let an admin
+      # create on behalf of another owner (e.g. read a param), then gate who may
+      # do so in #create? via `record.owner`.
+      def owner
+        current_user
+      end
+
+      # Should endpoints created through the API start `unverified` (receiving no
+      # deliveries until a successful ping verifies them)? Default: no, they go
+      # live immediately. Override to require endpoints to prove themselves first.
+      def create_unverified?
+        false
+      end
+
+      # May the API set allow_private_network? Default: no. This *relaxes* SSRF
+      # protection (delivery to private/loopback addresses), so an end user who
+      # can set it can point a webhook at your internal network. Trusted operators
+      # only.
+      def permit_allow_private_network?
+        false
+      end
+
+      # May the API set allowed_networks (a per-endpoint CIDR allowlist)? Default:
+      # no. Unlike allow_private_network this only *restricts* where an endpoint
+      # may deliver, so it's safe to expose more widely, but it's gated
+      # independently so you can allow it without allowing the private-network
+      # relaxation.
+      def permit_allowed_networks?
+        false
+      end
+
+      def index? = true
+      def show? = true
+      def create? = true
+      def update? = true
+      def destroy? = true
+
+      def rotate_secret? = update?
+      def pause? = update?
+      def enable? = update?
+      def verify? = update?
+      def ping? = update?
+      def redeliver? = update?
+    end
+  end
+end

data/app/validators/angarium/endpoint_url_validator.rb

@@ -0,0 +1,20 @@
+module Angarium
+  class EndpointUrlValidator < ActiveModel::EachValidator
+    def validate_each(record, attribute, value)
+      uri = begin
+        URI.parse(value.to_s)
+      rescue URI::InvalidURIError
+        nil
+      end
+
+      unless uri.is_a?(URI::HTTPS) && uri.host.present?
+        record.errors.add(attribute, "must be a valid https URL")
+        return
+      end
+
+      unless AddressPolicy.host_permitted_for_validation?(uri.host, record)
+        record.errors.add(attribute, "resolves to a disallowed address")
+      end
+    end
+  end
+end

data/app/views/layouts/angarium/application.html.erb

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Angarium</title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%= stylesheet_link_tag    "angarium/application", media: "all" %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,22 @@
+Angarium::Engine.routes.draw do
+  # Headless JSON API. Mount the engine in your app's routes, e.g.
+  #   mount Angarium::Engine => "/webhooks"
+  # yielding /webhooks/endpoints, /webhooks/deliveries/:id, etc.
+  scope module: :api, defaults: {format: :json} do
+    resources :endpoints, only: %i[index show create update destroy] do
+      member do
+        post :rotate_secret
+        post :pause
+        post :enable
+        post :verify
+        post :ping
+      end
+      resources :deliveries, only: %i[index]
+    end
+
+    resources :deliveries, only: %i[show] do
+      member { post :redeliver }
+      resources :attempts, only: %i[index]
+    end
+  end
+end

data/db/angarium_migrate/20260704000001_create_angarium_endpoints.rb

@@ -0,0 +1,22 @@
+class CreateAngariumEndpoints < ActiveRecord::Migration[7.1]
+  def change
+    create_table :angarium_endpoints, id: Angarium.primary_key_type do |t|
+      t.references :owner, polymorphic: true, null: false, type: :string
+      t.string :name, null: false
+      t.string :url, null: false
+      t.string :status, null: false, default: "enabled"
+      t.text :signing_secret, null: false
+      t.json :subscribed_events, null: false, default: []
+      t.boolean :allow_private_network, null: false, default: false
+      t.json :allowed_networks, null: false, default: []
+      # Encrypted at rest (may hold a receiver credential), so it's nullable with
+      # no DB default — an unencrypted default would fail to decrypt on read.
+      t.json :custom_headers
+      t.integer :consecutive_failures, null: false, default: 0
+      t.text :previous_signing_secret
+      t.datetime :secret_rotated_at
+      t.datetime :status_changed_at
+      t.timestamps
+    end
+  end
+end

data/db/angarium_migrate/20260704000002_create_angarium_events.rb

@@ -0,0 +1,9 @@
+class CreateAngariumEvents < ActiveRecord::Migration[7.1]
+  def change
+    create_table :angarium_events, id: Angarium.primary_key_type do |t|
+      t.string :name, null: false
+      t.json :payload, null: false, default: {}
+      t.timestamps
+    end
+  end
+end

data/db/angarium_migrate/20260704000003_create_angarium_deliveries.rb

@@ -0,0 +1,13 @@
+class CreateAngariumDeliveries < ActiveRecord::Migration[7.1]
+  def change
+    create_table :angarium_deliveries, id: Angarium.primary_key_type do |t|
+      t.references :event, null: false, type: Angarium.primary_key_type, foreign_key: {to_table: :angarium_events}
+      t.references :endpoint, null: false, type: Angarium.primary_key_type, foreign_key: {to_table: :angarium_endpoints}
+      t.string :state, null: false, default: "pending"
+      t.integer :attempt_count, null: false, default: 0
+      t.datetime :last_attempt_at
+      t.datetime :next_attempt_at
+      t.timestamps
+    end
+  end
+end