Skip to main content
Webhook endpoint methods require SDK 3.0.0 or later (the Paubox_Webhooks_SDK module itself reports version 2.3.1 in that release). They are on Paubox_Webhooks_SDK, not on the Paubox_Email_SDK object you use to send email.
Paubox_Webhooks_SDK 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.

Create the client

When apiKey is omitted, new() reads WEBHOOKS_API_KEY from config.cfg in the working directory:
Every method dies before sending a request if no key is set. The base URL can’t be changed.

Events

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

Every method except deleteWebhookEndpoint returns the raw JSON response body; decode it with from_json. The hashref argument is optional. 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

target_url must be an https URL that doesn’t point at a private or internal address. Responses for a single endpoint wrap it in data. Each endpoint has 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

Update a webhook endpoint

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

Delete a webhook endpoint

Returns 1.

Error handling

Methods die on a non-2xx response with the API’s error text; the HTTP status isn’t included unless the response body is empty, in which case the message is “Request failed with HTTP status N.” Creating a second endpoint for the same target_url returns 422, and an ID that isn’t on your account returns 404. An ID that isn’t a UUID dies before any request is sent.