Rails SDK webhook client

Webhook endpoint methods require paubox_rails 1.2.0 or later. They are on PauboxRails::Webhooks::Client, not on Paubox::Client from the paubox gem.

PauboxRails::Webhooks::Client manages webhook endpoints through the Paubox webhooks service at https://api.paubox.com/v1/webhooks. It sends a scoped API key as Authorization: Bearer YOUR_API_KEY. The key’s scopes decide which events it can subscribe to. It doesn’t use the api_key from Paubox.configure.

Create the client

webhooks = PauboxRails::Webhooks.client(api_key: 'YOUR_API_KEY')

When api_key: is omitted, the client reads the PAUBOX_WEBHOOKS_API_KEY environment variable. Pass base_url: or set PAUBOX_WEBHOOKS_URL to override the base URL. Every method raises PauboxRails::Webhooks::MissingApiKeyError before sending a request if no key is set.

Events

Event	Required scope	Fires when
`api_mail_log_delivered`	`email_api`	An Email API message is delivered
`api_mail_log_opened`	`email_api`	A delivered message is opened
`api_mail_log_temporary_failure`	`email_api`	Delivery fails temporarily
`api_mail_log_permanent_failure`	`email_api`	Delivery fails permanently
`email.inbound.received`	`email_api`, with no sender-domain limit	Inbound mail is received
`forms.submission.created`	`forms`	A form submission is received

The SDK doesn’t check event names. The API returns 422 for an unknown event and 403 for an event the key isn’t scoped for. Email API keys created in the Paubox Dashboard are limited to a sender domain, so subscribe to inbound mail in the Paubox Dashboard under Settings > Webhooks. For payloads and signature verification, see Webhooks.

List webhook endpoints

result = webhooks.list_webhook_endpoints(page: 1, items: 50)

result['data'].each do |endpoint|
  puts "#{endpoint['id']} #{endpoint['target_url']} #{endpoint['status']}"
end
puts result['page_info']['count']

page: and items: are optional. The result is the parsed response, with data and page_info; page_info['count'] is the total number of endpoints, not the length of this page. Endpoints carrying an event the key isn’t scoped for are left out.

Create a webhook endpoint

endpoint = webhooks.create_webhook_endpoint(
  target_url: 'https://example.com/webhooks/paubox',
  events: ['api_mail_log_delivered', 'api_mail_log_opened']
)

puts endpoint['id']
puts endpoint['signing_secret']

target_url: must be an https URL that doesn’t point at a private or internal address. Each endpoint is a hash with id (a UUID), target_url, status (active or disabled), events, created_at, and updated_at. signing_secret is returned only by this call; store it when you create the endpoint. To replace a lost secret, delete the endpoint and create a new one.

Get a webhook endpoint

endpoint = webhooks.get_webhook_endpoint('2ec66c21-bf48-48eb-8d28-f80b2d6b77c7')

Update a webhook endpoint

endpoint = webhooks.update_webhook_endpoint('2ec66c21-bf48-48eb-8d28-f80b2d6b77c7', status: 'disabled')

Pass any of target_url:, status: ('active' or 'disabled'), and events:. Only the arguments you pass are sent. events: replaces the endpoint’s event list.

Delete a webhook endpoint

webhooks.delete_webhook_endpoint('2ec66c21-bf48-48eb-8d28-f80b2d6b77c7')

Returns true.

Error handling

begin
  webhooks.create_webhook_endpoint(
    target_url: 'https://example.com/webhooks/paubox',
    events: ['api_mail_log_delivered']
  )
rescue PauboxRails::Webhooks::Error => e
  puts e.class
  puts e.message
end

Errors are subclasses of PauboxRails::Webhooks::Error: BadRequestError (400 or 422), UnauthorizedError (401), ForbiddenError (403), and NotFoundError (404). Other statuses raise PauboxRails::Webhooks::Error itself, with the status code and raw response body in the message. For 400, 401, 403 and 422 the message is the API’s error text; NotFoundError always says “Webhook endpoint not found”. Creating a second endpoint for the same target_url raises BadRequestError, and an ID that isn’t on your account raises NotFoundError. An ID that isn’t a UUID raises ArgumentError before any request is sent.

Get started

Email API

Migrate to Paubox

Marketing API

MCP Server

SDKs

CLI

Forms API

Create the client

Events

List webhook endpoints

Create a webhook endpoint

Get a webhook endpoint

Update a webhook endpoint

Delete a webhook endpoint

Error handling

​Create the client

​Events

​List webhook endpoints

​Create a webhook endpoint

​Get a webhook endpoint

​Update a webhook endpoint

​Delete a webhook endpoint

​Error handling

Create the client

Events

List webhook endpoints

Create a webhook endpoint

Get a webhook endpoint

Update a webhook endpoint

Delete a webhook endpoint

Error handling