paubox_rails 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f68c141779c45bbf28b520f210535ef3ff6abe9535925b631256f3c582f1cc85
-  data.tar.gz: b1f1e5e738b0c4b4b0f1dc459302e9caf04de4c8d39fccb10e50777714e81fc8
+  metadata.gz: a972155ed90a4c432adfbf7751a10ddcc234be6a581f3ce0ce25ee772676203f
+  data.tar.gz: 63a11cb9f8e8fdf508658807638da111f62ae36c41829d9203d9c81ecbf53a3e
 SHA512:
-  metadata.gz: 15998c19e36e66f59e0c0e7152d445e42d61d33cff4627375b66a07f7e1f0fe0aa50d16fc3d8366beef487045e5df2b4f5dec87f90177a1efe7f5c624c30794a
-  data.tar.gz: af6a73ed219c68acf1fbb58d05f9a827f49e9ed6e97d4e9c5274a4058b6330f58e96973f24df65156a195e5c03367257e32962c9d55ab8c179e02c42e9c56184
+  metadata.gz: 7cad38c91127705763494a330c81783ae79a884f46379ee7eec2a6b2682a7f919ca6012c1bf2349731a76e6d7daa693dca33e913c97edc4651af98aa4f7bbd0b
+  data.tar.gz: c5c599dc45256ed136dd65eb7e0c006d45cbf76286995eadc388f0e967a0a1adb1d1ce43aa90772e824fb72034ce4ed1fd0815f18f1d6dd46160401af2bf3e42

data/.github/workflows/ci.yml

@@ -47,7 +47,15 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Probe the Forms base URL the client uses
+      - name: Probe the base URLs the clients use
         run: |
-          grep -hoE 'https://api\.paubox\.com[a-zA-Z0-9/_.-]*' lib/paubox_rails/forms.rb \
-            | .github/scripts/route-check.sh
+          {
+            grep -hoE 'https://api\.paubox\.com[a-zA-Z0-9/_.-]*' lib/paubox_rails/forms.rb
+            # The webhooks base is probed with /endpoints appended. The gateway
+            # scopes its rule to that one resource so the producers' /v1/events
+            # ingest route stays off the public host, which leaves the bare base
+            # unrouted by design — probing it directly would fail this check for
+            # a URL the client never requests on its own.
+            grep -hoE 'https://api\.paubox\.com[a-zA-Z0-9/_.-]*' lib/paubox_rails/webhooks.rb \
+              | sed 's#/*$#/endpoints#'
+          } | .github/scripts/route-check.sh

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "1.1.0"
+  ".": "1.2.0"
 }

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.2.0](https://github.com/Paubox/paubox-rails/compare/v1.1.0...v1.2.0) (2026-10-14)
+
+
+### Features
+
+* add a client for the pb_webhooks service ([#25](https://github.com/Paubox/paubox-rails/issues/25)) ([910dfd0](https://github.com/Paubox/paubox-rails/commit/910dfd0fa3eea024eeabcc23180ad5a95c0b5bc8))
+
 ## [1.1.0](https://github.com/Paubox/paubox-rails/compare/v1.0.0...v1.1.0) (2026-09-10)
 
 

data/README.md

@@ -204,6 +204,90 @@ File.write('submissions.csv', client.submissions_csv(form_id))
 
 Also available: `get_form_details`, `update_form`, `archive_form`, `unarchive_form`, `copy_form`, `form_stats`, and `submission_pdf`. See [api.md](api.md) for the full Forms API reference.
 
+## Webhooks
+
+A webhook endpoint is a URL you own that Paubox notifies when something happens. `PauboxRails::Webhooks` manages those subscriptions: which URL to notify, and for which events.
+
+Build a client with an API key scoped for the events you want, or rely on the `PAUBOX_WEBHOOKS_API_KEY` environment variable:
+
+```ruby
+client = PauboxRails::Webhooks.client(api_key: ENV['PAUBOX_WEBHOOKS_API_KEY'])
+
+# or, reading the environment variable itself:
+client = PauboxRails::Webhooks.client
+```
+
+The key is sent as an `Authorization: Bearer` header — not the Email API's `Token token=`. Calling a method without one raises `PauboxRails::Webhooks::MissingApiKeyError` before any HTTP request is made. Unlike the Forms client, the base URL is overridable, via `base_url:` or `PAUBOX_WEBHOOKS_URL`, so staging QA does not require editing the gem.
+
+Which events a key may subscribe to follows from its scopes. The SDK does not inspect them — the service refuses an event the key isn't scoped for with 403 (`ForbiddenError`), and an unrecognised event with 422.
+
+**Available events**
+
+| Event | Fires when |
+| --- | --- |
+| `forms.submission.created` | A form submission is received |
+| `api_mail_log_delivered` | An Email API message is delivered |
+| `api_mail_log_opened` | A delivered message is opened |
+| `api_mail_log_temporary_failure` | Delivery fails temporarily |
+| `api_mail_log_permanent_failure` | Delivery fails permanently |
+| `email.inbound.received` | Inbound mail is received |
+
+The four Email API events keep their legacy `api_mail_log_` names, so a receiver written
+against the old Email API webhooks keeps working unchanged. Note these are the names on
+the wire: `delivered` or `failed` on their own are rejected as unknown.
+
+The SDK does not check these names. The catalog lives in the service, so an event added
+later works here without upgrading the SDK.
+
+### Creating a webhook endpoint
+
+```ruby
+endpoint = client.create_webhook_endpoint(
+  target_url: 'https://example.com/paubox-webhook',
+  events: ['forms.submission.created']
+)
+
+endpoint['id']             # UUID
+endpoint['signing_secret'] # whsec_... — store this now
+```
+
+`signing_secret` is returned **once**, here. It is absent from `get_webhook_endpoint` and `list_webhook_endpoints`, and there is no way to read it back — recovering from a lost secret means deleting the endpoint and creating a new one. Use it to verify that deliveries really came from Paubox.
+
+### Listing, fetching, updating and deleting
+
+```ruby
+# Returns the full document: "data" plus "page_info"
+result = client.list_webhook_endpoints
+result['page_info']['count'] # total matching, not the length of this page
+
+client.list_webhook_endpoints(page: 2, items: 25)
+
+client.get_webhook_endpoint('2ec66c21-bf48-48eb-8d28-f80b2d6b77c7')
+
+# Only the keyword arguments you pass are sent
+client.update_webhook_endpoint(endpoint_id, status: 'disabled')
+
+client.delete_webhook_endpoint(endpoint_id)
+```
+
+Pausing deliveries without losing the subscription is what `disabled` is for; pass `active` to resume. Passing `events:` replaces the list rather than adding to it. Delete answers `204 No Content`, stops every event on that endpoint, and takes the signing secret with it.
+
+### Error handling
+
+Failures raise a `PauboxRails::Webhooks::Error` subclass chosen by status — `BadRequestError`, `UnauthorizedError`, `ForbiddenError`, `NotFoundError` — with the service's own message rather than a bare status:
+
+```ruby
+begin
+  client.create_webhook_endpoint(target_url: url, events: ['forms.submission.created'])
+rescue PauboxRails::Webhooks::Error => e
+  e.message # "target_url: an endpoint already exists for this URL"
+end
+```
+
+Two cases worth handling explicitly: subscribing a `target_url` that already has an endpoint comes back as 422, and an id that doesn't belong to your account is a 404 rather than a 403. An id that isn't a UUID raises `ArgumentError` locally, before any request is made.
+
+See [api.md](api.md) for the full webhooks reference.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/paubox/paubox-rails.

data/api.md

@@ -1,9 +1,10 @@
 # Paubox API Reference
 
-This document covers the API endpoints exposed by `paubox-rails`. The gem wraps two separate Paubox services:
+This document covers the API endpoints exposed by `paubox-rails`. The gem wraps three separate Paubox services:
 
 - **Email API** — authenticated, delegates to the [`paubox`](https://github.com/paubox/paubox_ruby) gem via ActionMailer
 - **Forms API** — public respondent endpoints plus authenticated management endpoints, implemented directly in this gem
+- **Webhooks API** — authenticated subscription management, implemented directly in this gem
 
 ---
 
@@ -689,3 +690,197 @@ File.binwrite('submission.pdf', pdf)
 Email delivery is handled transparently by ActionMailer using the `:paubox` delivery method. There is no direct HTTP interaction in this gem — all email API calls are delegated to the [`paubox`](https://github.com/paubox/paubox_ruby) gem.
 
 See the [Paubox Ruby gem documentation](https://github.com/paubox/paubox_ruby) for the full Email API reference, including message status tracking and templated messages.
+
+---
+
+## Webhooks API
+
+**Base URL:** `https://api.paubox.com/v1/webhooks`
+
+Every request carries the `/endpoints` resource. The bare base is unrouted on the public gateway by design: the rule is scoped to `/endpoints` so the producers' event-ingest route stays private. Unlike Forms, the base is overridable with `base_url:` or `PAUBOX_WEBHOOKS_URL`.
+
+### Authentication
+
+An API key scoped for the events you want, sent as a Bearer header:
+
+```
+Authorization: Bearer <SCOPED_API_KEY>
+```
+
+Read from `PAUBOX_WEBHOOKS_API_KEY` when not passed explicitly. Calling a method without a key raises `MissingApiKeyError` before any request is sent. Which events a key may subscribe to follows from its scopes; the gem does not inspect them, so an event the key is not scoped for returns 403 and an unrecognised one 422.
+
+**Available events**
+
+| Event | Fires when |
+| --- | --- |
+| `forms.submission.created` | A form submission is received |
+| `api_mail_log_delivered` | An Email API message is delivered |
+| `api_mail_log_opened` | A delivered message is opened |
+| `api_mail_log_temporary_failure` | Delivery fails temporarily |
+| `api_mail_log_permanent_failure` | Delivery fails permanently |
+| `email.inbound.received` | Inbound mail is received |
+
+The four Email API events keep their legacy `api_mail_log_` names, so a receiver written
+against the old Email API webhooks keeps working unchanged. Note these are the names on
+the wire: `delivered` or `failed` on their own are rejected as unknown.
+
+The SDK does not check these names. The catalog lives in the service, so an event added
+later works here without upgrading the SDK.
+
+```ruby
+client = PauboxRails::Webhooks.client(api_key: ENV['PAUBOX_WEBHOOKS_API_KEY'])
+```
+
+---
+
+### List Webhook Endpoints
+
+**GET** `/endpoints`
+
+Returns the endpoints this key can act on. Endpoints carrying an event the key is not scoped for are filtered out by the service.
+
+**Query parameters:**
+- `page` (integer, optional) — 1-based page number
+- `items` (integer, optional) — page size
+
+**Response (200):**
+```json
+{
+  "data": [
+    {
+      "id": "2ec66c21-bf48-48eb-8d28-f80b2d6b77c7",
+      "target_url": "https://example.com/paubox-webhook",
+      "status": "active",
+      "events": ["forms.submission.created"],
+      "created_at": "2026-10-09T01:43:41.639968+00:00",
+      "updated_at": "2026-10-09T01:43:41.639968+00:00"
+    }
+  ],
+  "page_info": { "count": 1, "items": 50 }
+}
+```
+
+`page_info.count` is the total number of matching endpoints, not the length of `data`.
+
+```ruby
+result = client.list_webhook_endpoints
+result = client.list_webhook_endpoints(page: 2, items: 25)
+```
+
+Returns the full document — `data` plus `page_info` — since a caller paginating needs both.
+
+---
+
+### Create Webhook Endpoint
+
+**POST** `/endpoints`
+
+**Request body:**
+- `target_url` (string, required) — an https URL resolving to a publicly routable address
+- `events` (array of strings, required, non-empty)
+
+**Response (201):**
+```json
+{
+  "data": {
+    "id": "2ec66c21-bf48-48eb-8d28-f80b2d6b77c7",
+    "target_url": "https://example.com/paubox-webhook",
+    "status": "active",
+    "events": ["forms.submission.created"],
+    "created_at": "2026-10-09T01:43:41.639968+00:00",
+    "updated_at": "2026-10-09T01:43:41.639968+00:00",
+    "signing_secret": "whsec_..."
+  },
+  "message": "Store this signing_secret now — it is not shown again."
+}
+```
+
+`signing_secret` is returned only here. It is absent from get and list, and cannot be read back: recovering from a lost secret means replacing the endpoint.
+
+**Errors:**
+- `422` (`BadRequestError`) — missing or malformed `target_url`, an empty `events`, an unrecognised event, or a `target_url` that already has an endpoint
+- `403` (`ForbiddenError`) — an event this key is not scoped for
+
+```ruby
+endpoint = client.create_webhook_endpoint(
+  target_url: 'https://example.com/paubox-webhook',
+  events: ['forms.submission.created']
+)
+endpoint['signing_secret']
+```
+
+Returns the endpoint itself, unwrapped from the `data` envelope.
+
+---
+
+### Get Webhook Endpoint
+
+**GET** `/endpoints/<id>`
+
+**Path parameter:**
+- `endpoint_id` (UUID, required)
+
+**Response (200):** the endpoint, wrapped in `data`. The signing secret is not included.
+
+**Errors:**
+- `404` (`NotFoundError`) — no such endpoint, or it belongs to another account
+
+```ruby
+client.get_webhook_endpoint('2ec66c21-bf48-48eb-8d28-f80b2d6b77c7')
+```
+
+An id that is not UUID-shaped raises `ArgumentError` before any request is sent.
+
+---
+
+### Update Webhook Endpoint
+
+**PATCH** `/endpoints/<id>`
+
+A partial update: only the fields sent are changed.
+
+**Request body (all optional, at least one required):**
+- `target_url` (string)
+- `status` (string) — `"active"` or `"disabled"`
+- `events` (array of strings) — replaces the list rather than adding to it
+
+**Response (200):** the updated endpoint, wrapped in `data`.
+
+```ruby
+client.update_webhook_endpoint(endpoint_id, status: 'disabled')
+client.update_webhook_endpoint(endpoint_id, target_url: 'https://example.com/new-hook')
+```
+
+`disabled` pauses deliveries without losing the subscription; `active` resumes them.
+
+---
+
+### Delete Webhook Endpoint
+
+**DELETE** `/endpoints/<id>`
+
+**Response:**
+- `204` — deleted, no body
+- `404` (`NotFoundError`) — no such endpoint, or it belongs to another account
+
+Deleting stops every event on that endpoint and discards its signing secret.
+
+```ruby
+client.delete_webhook_endpoint(endpoint_id) # => true
+```
+
+---
+
+### Webhook Errors
+
+Failures raise a subclass of `PauboxRails::Webhooks::Error`, chosen by status:
+
+| Status | Class |
+|---|---|
+| 400, 422 | `BadRequestError` |
+| 401 | `UnauthorizedError` |
+| 403 | `ForbiddenError` |
+| 404 | `NotFoundError` |
+| no API key | `MissingApiKeyError` |
+
+The message is unwrapped from the service's `{"message": "..."}` shape rather than interpolating the raw body, so a caller sees `target_url: must be an https URL` instead of a JSON blob. An unexpected shape falls back to the raw body so nothing is lost.

data/lib/paubox_rails/version.rb

@@ -1,3 +1,3 @@
 module PauboxRails
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

data/lib/paubox_rails/webhooks/client.rb

@@ -0,0 +1,210 @@
+require 'net/http'
+require 'json'
+require 'uri'
+
+module PauboxRails
+  module Webhooks
+    # Client for the Paubox webhooks service.
+    #
+    # Authenticates with a scoped API key sent as "Authorization: Bearer
+    # <key>" — the same scheme as Forms, and a different one from the Email
+    # API's "Token token=". Which events a key may subscribe to is decided by
+    # its scopes; asking for one it is not scoped for is refused with 403.
+    class Client
+      UUID_PATTERN = /\A[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\z/.freeze
+
+      # Net::HTTP ships with no default socket timeouts, so a black-holed
+      # connection hangs for the TCP stack default rather than raising. These
+      # are tighter than the Forms client's because nothing here streams a
+      # CSV or a PDF — every response is a small JSON document.
+      DEFAULT_OPEN_TIMEOUT = 10
+      DEFAULT_READ_TIMEOUT = 30
+
+      attr_reader :api_key, :base_url
+
+      def initialize(api_key: ENV.fetch(ENV_API_KEY, nil), base_url: nil)
+        @api_key = api_key
+        @base_url = (base_url || ENV.fetch(ENV_BASE_URL, nil) || BASE_URL).sub(%r{/+\z}, '')
+      end
+
+      # Lists the endpoints this key can act on. Endpoints carrying an event
+      # the key is not scoped for are filtered out by the service, so this is
+      # what the key may manage rather than everything on the account.
+      #
+      # Returns the full document: "data" plus "page_info". Note page_info
+      # "count" is the total number of matching endpoints, not the length of
+      # this page.
+      def list_webhook_endpoints(page: nil, items: nil)
+        authenticated_get("/endpoints#{build_query(page: page, items: items)}")
+      end
+
+      # Subscribes a URL to one or more events.
+      #
+      # The response carries "signing_secret", which the service returns only
+      # here — it is absent from get_webhook_endpoint and from the list. Store
+      # it on receipt; a lost secret means replacing the endpoint.
+      #
+      # Event names are not validated here on purpose: the catalog belongs to
+      # the service and grows without a gem release. An unknown event comes
+      # back as 422, one this key is not scoped for as 403.
+      def create_webhook_endpoint(target_url:, events:)
+        raise ArgumentError, 'target_url is required' if target_url.nil? || target_url.to_s.empty?
+        raise ArgumentError, 'events must not be empty' if events.nil? || Array(events).empty?
+
+        unwrap_data(
+          authenticated_post('/endpoints', body: { target_url: target_url, events: Array(events) })
+        )
+      end
+
+      def get_webhook_endpoint(endpoint_id)
+        endpoint_id = path_segment!(endpoint_id, 'endpoint_id')
+        unwrap_data(authenticated_get("/endpoints/#{endpoint_id}"))
+      end
+
+      # Partial update — only the arguments given are sent, so changing
+      # target_url leaves events and status untouched. status accepts
+      # "active" or "disabled".
+      def update_webhook_endpoint(endpoint_id, target_url: nil, status: nil, events: nil)
+        endpoint_id = path_segment!(endpoint_id, 'endpoint_id')
+
+        body = {}
+        body[:target_url] = target_url unless target_url.nil?
+        body[:status] = status unless status.nil?
+        body[:events] = Array(events) unless events.nil?
+        raise ArgumentError, 'provide at least one of target_url:, status:, events:' if body.empty?
+
+        unwrap_data(authenticated_patch("/endpoints/#{endpoint_id}", body: body))
+      end
+
+      # Deletes an endpoint, stopping every event on it. The service answers
+      # 204 with no body, so this returns true rather than a document.
+      def delete_webhook_endpoint(endpoint_id)
+        endpoint_id = path_segment!(endpoint_id, 'endpoint_id')
+        authenticated_delete("/endpoints/#{endpoint_id}")
+      end
+
+      private
+
+      # Single resources come back wrapped: {"data": {...}}. Unwrapped here so
+      # callers get the endpoint itself rather than having to reach through an
+      # envelope that carries nothing else.
+      #
+      # list_webhook_endpoints deliberately does not use this — its envelope
+      # also carries "page_info", which a caller paginating actually needs.
+      def unwrap_data(parsed)
+        parsed.is_a?(Hash) && parsed.key?('data') ? parsed['data'] : parsed
+      end
+
+      # Sanitize a caller-supplied id before interpolating it into a URL path.
+      # Without this, a value containing "..", "/", "?" or "#" changes which
+      # endpoint is called — and since the Authorization header goes on the
+      # same host, the key rides along on the retargeted request. Unlike the
+      # Forms client there is no public-endpoint exception here: every id on
+      # this service is a UUID, so the strict check applies throughout.
+      def path_segment!(value, name)
+        raise ArgumentError, "#{name} is required and must not be empty" if value.nil? || value.to_s.empty?
+
+        s = value.to_s
+        raise ArgumentError, "#{name} must be a UUID, got #{s.inspect}" if s !~ UUID_PATTERN
+
+        # A no-op for a UUID; kept as defense-in-depth so the guarantee holds
+        # if the pattern is ever relaxed.
+        URI.encode_www_form_component(s).gsub('+', '%20')
+      end
+
+      def authenticated_get(path)
+        require_api_key!
+        uri = URI.parse("#{@base_url}#{path}")
+        request = Net::HTTP::Get.new(uri.request_uri, auth_headers)
+        handle_response(build_http(uri).request(request))
+      end
+
+      def authenticated_post(path, body: nil)
+        require_api_key!
+        uri = URI.parse("#{@base_url}#{path}")
+        request = Net::HTTP::Post.new(uri.request_uri, auth_headers('Content-Type' => 'application/json'))
+        request.body = body.to_json if body
+        handle_response(build_http(uri).request(request))
+      end
+
+      def authenticated_patch(path, body: nil)
+        require_api_key!
+        uri = URI.parse("#{@base_url}#{path}")
+        request = Net::HTTP::Patch.new(uri.request_uri, auth_headers('Content-Type' => 'application/json'))
+        request.body = body.to_json if body
+        handle_response(build_http(uri).request(request))
+      end
+
+      def authenticated_delete(path)
+        require_api_key!
+        uri = URI.parse("#{@base_url}#{path}")
+        request = Net::HTTP::Delete.new(uri.request_uri, auth_headers)
+        handle_response(build_http(uri).request(request))
+      end
+
+      def auth_headers(extra = {})
+        { 'Authorization' => "Bearer #{@api_key}" }.merge(extra)
+      end
+
+      def require_api_key!
+        return if @api_key
+
+        raise MissingApiKeyError, 'This endpoint requires an API key. Pass api_key: to ' \
+                                  'PauboxRails::Webhooks.client or set the ' \
+                                  "#{ENV_API_KEY} environment variable."
+      end
+
+      def build_query(params)
+        filtered = params.reject { |_key, value| value.nil? }
+        return '' if filtered.empty?
+
+        "?#{URI.encode_www_form(filtered)}"
+      end
+
+      def build_http(uri)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == 'https'
+        http.open_timeout = DEFAULT_OPEN_TIMEOUT
+        http.read_timeout = DEFAULT_READ_TIMEOUT
+        http
+      end
+
+      # Differs from the Forms client in two ways that matter.
+      #
+      # 201 returns the parsed body rather than true: create is the only place
+      # the signing secret is ever available, and returning true would throw
+      # it away irrecoverably.
+      #
+      # Error messages are unwrapped from the service's {"message": "..."}
+      # shape instead of interpolating the raw body, so a caller sees
+      # "target_url: must be an https URL" rather than a JSON blob.
+      def handle_response(response)
+        case response.code.to_i
+        when 200, 201
+          response.body.to_s.empty? ? true : JSON.parse(response.body)
+        when 204
+          true
+        when 400, 422
+          raise BadRequestError, error_message(response)
+        when 401
+          raise UnauthorizedError, error_message(response)
+        when 403
+          raise ForbiddenError, error_message(response)
+        when 404
+          raise NotFoundError, 'Webhook endpoint not found'
+        else
+          raise Error, "Unexpected response #{response.code}: #{response.body}"
+        end
+      end
+
+      # Falls back to the raw body so an unexpected shape still reaches the
+      # caller rather than becoming an empty message.
+      def error_message(response)
+        parsed = JSON.parse(response.body.to_s)
+        parsed.is_a?(Hash) && parsed['message'] ? parsed['message'] : response.body.to_s
+      rescue JSON::ParserError
+        response.body.to_s
+      end
+    end
+  end
+end

data/lib/paubox_rails/webhooks.rb

@@ -0,0 +1,28 @@
+require 'paubox_rails/webhooks/client'
+
+module PauboxRails
+  module Webhooks
+    # The public gateway exposes only /v1/webhooks/endpoints and rewrites it
+    # onto the service's own /v1/endpoints, so the producers' event-ingest
+    # route is not reachable from here. The bare base is deliberately unrouted;
+    # every request this client makes carries the /endpoints resource.
+    BASE_URL = 'https://api.paubox.com/v1/webhooks'.freeze
+
+    # Unlike Forms, the base URL is overridable. Staging QA needs it, and
+    # hardcoding it is why pointing the Forms client at a non-production
+    # environment means editing the gem.
+    ENV_BASE_URL = 'PAUBOX_WEBHOOKS_URL'.freeze
+    ENV_API_KEY = 'PAUBOX_WEBHOOKS_API_KEY'.freeze
+
+    class Error < StandardError; end
+    class NotFoundError < Error; end
+    class BadRequestError < Error; end
+    class UnauthorizedError < Error; end
+    class ForbiddenError < Error; end
+    class MissingApiKeyError < Error; end
+
+    def self.client(**options)
+      Client.new(**options)
+    end
+  end
+end

data/lib/paubox_rails.rb

@@ -2,6 +2,7 @@ require "paubox_rails/version"
 require 'action_mailer'
 require 'paubox'
 require 'paubox_rails/forms'
+require 'paubox_rails/webhooks'
 
 module PauboxRails
   extend self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paubox_rails
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Paubox, Inc.
@@ -123,6 +123,8 @@ files:
 - lib/paubox_rails/forms/client.rb
 - lib/paubox_rails/railtie.rb
 - lib/paubox_rails/version.rb
+- lib/paubox_rails/webhooks.rb
+- lib/paubox_rails/webhooks/client.rb
 - paubox_rails.gemspec
 - release-please-config.json
 homepage: https://www.paubox.com