paubox 1.3.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 03c144256b933b90453a794a96dd10a17979ebd6672c4718c09105a440c5ec9e
-  data.tar.gz: 3b85993acff1094aea7ff20c415857e38e51ebde9329584bc5ab48ccb31dffb5
+  metadata.gz: aa4eb8413cee31b007b8dd6adb1dc4342891fab4f46869f68adabb7d3ac4a7a2
+  data.tar.gz: e310784bb8c7963d5e791662ecccebc50253f33c341864bd3260409e5594293a
 SHA512:
-  metadata.gz: c9453c28e1e1357ba079e274b46a0b7ec12414272e809658bf58e05abfaeedbcb68409f580089a72b95c24b9570214a1cabf2ee25fd4c740d0a30ba2424c66e5
-  data.tar.gz: 9ffef90ede4234b5b867670e3ba709512130b5af1aabb498567c1b333ada21d127cb4f1ce6b147e773443064af6e14621cb8ad4405a716c504df63f9e8eec2f1
+  metadata.gz: baff84836c819530292367f0ab8b2990afb4d5e46f9a8991fb72a2b93263f3566c4e37b8b5c842e965c6815445c23e895e86bf0b23357ac698796a74e27d2968
+  data.tar.gz: 9d2ba57f05e491258e4fba02d4d3c6cbc1690789b1a8eaf9ba4504b8c771d645a39f9ff61588c3fe939891ca9935b5fe825920e28119b74f1fffb07cac271308

data/.github/workflows/ci.yml

@@ -58,4 +58,11 @@ jobs:
             puts Paubox::Client.new.send(:api_base_endpoint)
             f = Paubox::FormsClient
             puts "#{f::FORMS_PROTOCOL}#{f::FORMS_HOST}#{f::FORMS_BASE}"
+            # The webhooks base is probed with /endpoints appended. The gateway
+            # scopes its rule to that one resource so the producers event-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.
+            w = Paubox::WebhooksClient
+            puts "#{w::WEBHOOKS_PROTOCOL}#{w::WEBHOOKS_HOST}#{w::WEBHOOKS_BASE}/endpoints"
           ' | .github/scripts/route-check.sh

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "1.3.0"
+  ".": "2.0.0"
 }

data/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.0.0](https://github.com/Paubox/paubox-ruby/compare/v1.3.1...v2.0.0) (2026-10-14)
+
+
+### ⚠ BREAKING CHANGES
+
+* move webhook CRUD to the pb_webhooks service ([#36](https://github.com/Paubox/paubox-ruby/issues/36))
+
+### Features
+
+* move webhook CRUD to the pb_webhooks service ([#36](https://github.com/Paubox/paubox-ruby/issues/36)) ([a27d3b6](https://github.com/Paubox/paubox-ruby/commit/a27d3b6c2643d21368235077e7a92cf28da3d7e4))
+
+## [1.3.1](https://github.com/Paubox/paubox-ruby/compare/v1.3.0...v1.3.1) (2026-10-02)
+
+
+### Bug Fixes
+
+* **receiving:** key attachment downloads on attachment_id and pass list filters ([#33](https://github.com/Paubox/paubox-ruby/issues/33)) ([875dea3](https://github.com/Paubox/paubox-ruby/commit/875dea3c1f897286061766aac6f73070288f4eab))
+
 ## [1.3.0](https://github.com/Paubox/paubox-ruby/compare/v1.2.0...v1.3.0) (2026-09-17)
 
 

data/README.md

@@ -497,6 +497,117 @@ pdf = client.submission_pdf('550e8400-e29b-41d4-a716-446655440000',
 File.binwrite('submission.pdf', pdf)
 ```
 
+<a name="#webhooks"></a>
+## Webhooks
+
+A webhook endpoint is a URL you own that Paubox notifies when something happens.
+`Paubox::WebhooksClient` manages those subscriptions: which URL to notify, and for which events.
+
+Every method needs an API key scoped for the events you want, sent as an `Authorization: Bearer`
+header — not the Email API's `Token token=`. Pass it to the constructor or configure it globally:
+
+```ruby
+require 'Paubox'
+
+client = Paubox::WebhooksClient.new(api_key: ENV['PAUBOX_WEBHOOKS_API_KEY'])
+
+# or globally:
+Paubox.configure { |config| config.webhooks_api_key = ENV['PAUBOX_WEBHOOKS_API_KEY'] }
+client = Paubox::WebhooksClient.new
+```
+
+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, 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 webhook endpoints
+
+```ruby
+result = client.list_webhook_endpoints
+
+result['data'].each do |endpoint|
+  puts [endpoint['id'], endpoint['target_url'], endpoint['status']].join(' ')
+end
+
+result['page_info']['count'] # total matching, not the length of this page
+
+# Paginated
+client.list_webhook_endpoints(page: 2, items: 25)
+```
+
+### Getting, updating and deleting
+
+```ruby
+endpoint = client.get_webhook_endpoint('2ec66c21-bf48-48eb-8d28-f80b2d6b77c7')
+
+# Only the keyword arguments you pass are sent
+endpoint = client.update_webhook_endpoint(id, status: 'disabled')
+
+client.delete_webhook_endpoint(id) # => true
+```
+
+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. Deleting answers `204 No
+Content`, stops every event on that endpoint, and takes the signing secret with it.
+
+### Error handling
+
+A non-2xx response raises `Paubox::WebhooksClient::Error`, carrying the service's own message
+rather than a bare status:
+
+```ruby
+begin
+  client.create_webhook_endpoint(target_url: url, events: ['forms.submission.created'])
+rescue Paubox::WebhooksClient::Error => e
+  e.status_code   # 422
+  e.message       # "target_url: an endpoint already exists for this URL"
+  e.response_body # raw response
+  e.url
+end
+```
+
+The error deliberately carries only those three fields, so an error reporter capturing locals from
+the raising frame never picks up the `Authorization` header or the API key.
+
+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, as does calling any
+method without an API key.
+
 <a name="#contributing"></a>
 ## Contributing
 

data/api.md

@@ -281,3 +281,217 @@ client.submit_form('550e8400-e29b-41d4-a716-446655440000',
     { name: 'consent.pdf', content: Base64.strict_encode64(File.binread('consent.pdf')) }
   ])
 ```
+
+---
+
+## Webhooks API
+
+A webhook endpoint is a URL you own that Paubox notifies when something happens. These endpoints
+manage those subscriptions.
+
+### Authentication
+
+An API key scoped for the events you want, sent as a Bearer header:
+
+```
+Authorization: Bearer <SCOPED_API_KEY>
+```
+
+Not the Email API's `Token token=`. Which events a key may subscribe to follows from its scopes;
+the SDK 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.
+
+### 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.
+
+---
+
+### 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 usage:**
+```ruby
+client = Paubox::WebhooksClient.new(api_key: ENV['PAUBOX_WEBHOOKS_API_KEY'])
+
+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` — missing or malformed `target_url`, an empty `events`, an unrecognised event, or a
+  `target_url` that already has an endpoint
+- `403` — an event this key is not scoped for
+
+**Ruby usage:**
+```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:**
+- `id` (UUID, required)
+
+**Response (200):** the endpoint, wrapped in `data`. The signing secret is not included.
+
+**Errors:**
+- `404` — no such endpoint, or it belongs to another account
+
+**Ruby usage:**
+```ruby
+endpoint = 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 usage:**
+```ruby
+client.update_webhook_endpoint(id, status: 'disabled')
+client.update_webhook_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` — no such endpoint, or it belongs to another account
+
+Deleting stops every event on that endpoint and discards its signing secret.
+
+**Ruby usage:**
+```ruby
+client.delete_webhook_endpoint(id) # => true
+```
+
+---
+
+### Webhook Errors
+
+Every non-2xx response raises `Paubox::WebhooksClient::Error`:
+
+```ruby
+begin
+  client.get_webhook_endpoint(id)
+rescue Paubox::WebhooksClient::Error => e
+  e.status_code   # Integer
+  e.message       # the service's own message, e.g. "webhook endpoint not found"
+  e.url
+  e.response_body # raw response
+end
+```
+
+The error carries only those fields, so an error reporter capturing locals from the raising frame
+never sees the `Authorization` header or the API key.

data/lib/paubox/client.rb

@@ -142,8 +142,9 @@ module Paubox
       JSON.parse(response.body)
     end
 
-    def list_received_emails(limit: nil, after: nil, before: nil)
-      params = { limit: limit, after: after, before: before }.compact
+    def list_received_emails(limit: nil, after: nil, before: nil, search: nil, sort: nil, ascending: nil)
+      params = { limit: limit, after: after, before: before,
+                 search: search, sort: sort, ascending: ascending }.compact
       query = params.map { |k, v| "#{k}=#{CGI.escape(v.to_s)}" }.join('&')
       url = request_endpoint('receiving')
       url = "#{url}?#{query}" unless query.empty?
@@ -157,41 +158,9 @@ module Paubox
       JSON.parse(response.body)
     end
 
-    def get_received_email_attachment(email_id, blob_id)
-      url = request_endpoint("receiving/#{email_id}/attachments/#{blob_id}")
-      RestClient.get(url, auth_header)
-    end
-
-    def list_webhook_endpoints
-      url = request_endpoint('webhook_endpoints')
-      response = RestClient.get(url, auth_header)
-      JSON.parse(response.body)
-    end
-
-    def create_webhook_endpoint(target_url:, events:, signing_key: nil, api_key: nil, active: true)
-      url = request_endpoint('webhook_endpoints')
-      payload = { target_url: target_url, events: events, active: active,
-                  signing_key: signing_key, api_key: api_key }.compact.to_json
-      response = RestClient.post(url, payload, auth_header)
-      JSON.parse(response.body)
-    end
-
-    def get_webhook_endpoint(id)
-      url = request_endpoint("webhook_endpoints/#{id}")
-      response = RestClient.get(url, auth_header)
-      JSON.parse(response.body)
-    end
-
-    def update_webhook_endpoint(id, **params)
-      url = request_endpoint("webhook_endpoints/#{id}")
-      response = RestClient.patch(url, params.to_json, auth_header)
-      JSON.parse(response.body)
-    end
-
-    def delete_webhook_endpoint(id)
-      url = request_endpoint("webhook_endpoints/#{id}")
-      response = RestClient.delete(url, auth_header)
-      JSON.parse(response.body)
+    def get_received_email_attachment(email_id, attachment_id)
+      url = request_endpoint("receiving/#{email_id}/attachments/#{attachment_id}")
+      RestClient.get(url, auth_header.merge(accept: '*/*'))
     end
 
     def send_request(method: :get, payload: {}, path: '')

data/lib/paubox/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Paubox
-  VERSION = '1.3.0'
+  VERSION = '2.0.0'
 end

data/lib/paubox/webhooks_client.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require 'cgi'
+require 'json'
+require 'rest-client'
+
+module Paubox
+  # Client for the Paubox webhooks service.
+  #
+  # Authenticates with a scoped API key sent as "Authorization: Bearer <key>",
+  # the same scheme as FormsClient and unlike 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 WebhooksClient
+    WEBHOOKS_HOST     = 'api.paubox.com'
+    WEBHOOKS_PROTOCOL = 'https://'
+    # 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 unreachable from here. The bare base is deliberately unrouted;
+    # every request below carries the /endpoints resource.
+    WEBHOOKS_BASE     = '/v1/webhooks'
+
+    TIMEOUT_SECONDS = 30
+
+    UUID_RE = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
+
+    # Raised on any non-2xx response. Carries only status_code / url /
+    # response_body so error reporters that capture raising-frame locals never
+    # see the Authorization header or api_key.
+    class Error < StandardError
+      attr_reader :status_code, :url, :response_body
+
+      def initialize(message, status_code: nil, url: nil, response_body: nil)
+        super(message)
+        @status_code   = status_code
+        @url           = url
+        @response_body = response_body
+      end
+    end
+
+    def initialize(args = {})
+      @host     = args[:host]     || WEBHOOKS_HOST
+      @protocol = args[:protocol] || WEBHOOKS_PROTOCOL
+      @base     = args[:base]     || WEBHOOKS_BASE
+      @api_key  = args[:api_key]  ||
+                  (Paubox.configuration && Paubox.configuration.webhooks_api_key)
+    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)
+      query = { page: page, items: items }.compact
+      url   = endpoint_url
+      url   = "#{url}?#{URI.encode_www_form(query)}" unless query.empty?
+
+      parse(request(method: :get, url: url, headers: auth_headers))
+    end
+
+    # Subscribes a URL to one or more events.
+    #
+    # The returned hash carries 'signing_secret', which the service sends 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?
+
+      payload = { target_url: target_url, events: Array(events) }.to_json
+      response = request(
+        method: :post, url: endpoint_url,
+        headers: auth_headers(content_type: :json), payload: payload
+      )
+      unwrap_data(parse(response))
+    end
+
+    def get_webhook_endpoint(id)
+      assert_uuid!(id, 'id')
+      unwrap_data(parse(request(method: :get, url: endpoint_url(id), headers: auth_headers)))
+    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(id, target_url: nil, status: nil, events: nil)
+      assert_uuid!(id, '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?
+
+      response = request(
+        method: :patch, url: endpoint_url(id),
+        headers: auth_headers(content_type: :json), payload: body.to_json
+      )
+      unwrap_data(parse(response))
+    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(id)
+      assert_uuid!(id, 'id')
+      request(method: :delete, url: endpoint_url(id), headers: auth_headers)
+      true
+    end
+
+    private
+
+    def endpoint_url(id = nil)
+      base = "#{@protocol}#{@host}#{@base}/endpoints"
+      id.nil? ? base : "#{base}/#{encode_segment(id)}"
+    end
+
+    def auth_headers(extra = {})
+      if @api_key.nil? || @api_key.to_s.empty?
+        raise ArgumentError, 'api_key is required for this endpoint. Pass a scoped ' \
+                             'API key: Paubox::WebhooksClient.new(api_key: ...), or set ' \
+                             'Paubox.configuration.webhooks_api_key'
+      end
+
+      { authorization: "Bearer #{@api_key}", accept: :json }.merge(extra)
+    end
+
+    def assert_uuid!(value, name)
+      return if value.is_a?(String) && value.match?(UUID_RE)
+
+      raise ArgumentError, "#{name} must be a UUID string (received #{value.inspect})"
+    end
+
+    def encode_segment(value)
+      CGI.escape(value.to_s)
+    end
+
+    def parse(response)
+      body = response.body.to_s
+      body.empty? ? nil : JSON.parse(body)
+    end
+
+    # Single resources arrive wrapped as {"data" => {...}}. Unwrapped so
+    # callers get the endpoint rather than an envelope carrying nothing else.
+    #
+    # list_webhook_endpoints deliberately skips this: its envelope also carries
+    # 'page_info', which a caller paginating needs.
+    def unwrap_data(parsed)
+      parsed.is_a?(Hash) && parsed.key?('data') ? parsed['data'] : parsed
+    end
+
+    # Funnels every request through RestClient::Request.execute so we can
+    # always set an explicit timeout (rest-client's default is nil) and
+    # translate ExceptionWithResponse into Paubox::WebhooksClient::Error,
+    # which carries only status_code / url / response_body — never the
+    # Authorization header or api_key. Keeps the Bearer token out of any error
+    # reporter that captures raising-frame locals.
+    #
+    # Unlike FormsClient the service's own message is promoted onto the
+    # exception when present, so a caller sees "target_url: must be an https
+    # URL" rather than only a status code.
+    def request(method:, url:, headers: {}, payload: nil)
+      RestClient::Request.execute(
+        method: method, url: url, payload: payload,
+        headers: headers, timeout: TIMEOUT_SECONDS
+      )
+    rescue RestClient::ExceptionWithResponse => e
+      response = e.response
+      code     = response && response.code
+      raise Error.new(
+        service_message(response) ||
+          "Paubox webhooks API request failed: #{e.class.name.split('::').last} " \
+          "(status #{code || 'unknown'})",
+        status_code:   code,
+        url:           url,
+        response_body: response && response.body
+      )
+    end
+
+    # The service answers failures as {"message": "..."}; anything else falls
+    # back to the generic message above.
+    def service_message(response)
+      return nil unless response
+
+      parsed = JSON.parse(response.body.to_s)
+      parsed.is_a?(Hash) && parsed['message'].is_a?(String) ? parsed['message'] : nil
+    rescue JSON::ParserError
+      nil
+    end
+  end
+end

data/lib/paubox.rb

@@ -11,6 +11,7 @@ require 'paubox/email_disposition'
 require 'paubox/form'
 require 'paubox/form_submission'
 require 'paubox/forms_client'
+require 'paubox/webhooks_client'
 require 'mail/paubox'
 
 module Paubox
@@ -24,7 +25,7 @@ module Paubox
   end
 
   class Configuration
-    attr_accessor :api_key, :forms_api_key
+    attr_accessor :api_key, :forms_api_key, :webhooks_api_key
 
     # Deprecated: api_user is no longer used by the Email API client.
     # Kept only for backward compatibility; it has no effect on requests.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paubox
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Paubox
@@ -178,6 +178,7 @@ files:
 - lib/paubox/message.rb
 - lib/paubox/templated_message.rb
 - lib/paubox/version.rb
+- lib/paubox/webhooks_client.rb
 - lib/paubox_ruby.rb
 - paubox_ruby.gemspec
 - release-please-config.json