Java SDK webhook client

The methods on this page require SDK 2.0.0 or later, where WebhookService uses the Paubox webhooks service and a scoped API key.

WebhookService 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 service

import com.paubox.service.WebhookInterface;
import com.paubox.service.WebhookService;

WebhookInterface webhooks = new WebhookService("YOUR_API_KEY");

new WebhookService() with no arguments uses WEBHOOKSAPIKEY from config.properties; load the file with ConfigurationManager.getProperties first. WebhookService doesn’t use APIKEY. Every method throws PauboxWebhooksException 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

WebhookEndpointListRequest request = new WebhookEndpointListRequest();
request.setPage(1);
request.setItems(50);

WebhookEndpointListResponse result = webhooks.listWebhookEndpoints(request);
for (WebhookEndpoint endpoint : result.getData()) {
    System.out.println(endpoint.getId() + " " + endpoint.getTargetUrl() + " " + endpoint.getStatus());
}
System.out.println(result.getPageInfo().getCount());

listWebhookEndpoints() with no arguments returns the first page. getPageInfo().getCount() 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

CreatedWebhookEndpoint created = webhooks.createWebhookEndpoint(
    new CreateWebhookEndpointRequest(
        "https://example.com/webhooks/paubox",
        Arrays.asList("api_mail_log_delivered", "api_mail_log_opened")));

System.out.println(created.getId());
System.out.println(created.getSigningSecret());

The target URL must be an https URL that doesn’t point at a private or internal address. WebhookEndpoint has getId() (a UUID), getTargetUrl(), getStatus() (active or disabled), getEvents(), getCreatedAt(), and getUpdatedAt(). CreatedWebhookEndpoint extends it with getSigningSecret(), which 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

WebhookEndpoint endpoint = webhooks.getWebhookEndpoint("2ec66c21-bf48-48eb-8d28-f80b2d6b77c7");

Update a webhook endpoint

UpdateWebhookEndpointRequest update = new UpdateWebhookEndpointRequest();
update.setStatus("disabled");

WebhookEndpoint updated = webhooks.updateWebhookEndpoint("2ec66c21-bf48-48eb-8d28-f80b2d6b77c7", update);

UpdateWebhookEndpointRequest has setTargetUrl, setStatus ("active" or "disabled"), and setEvents. Only the fields you set are sent. setEvents replaces the endpoint’s event list.

Delete a webhook endpoint

webhooks.deleteWebhookEndpoint("2ec66c21-bf48-48eb-8d28-f80b2d6b77c7");

Error handling

import com.paubox.common.PauboxWebhooksException;

try {
    webhooks.createWebhookEndpoint(new CreateWebhookEndpointRequest(
        "https://example.com/webhooks/paubox",
        Arrays.asList("api_mail_log_delivered")));
} catch (PauboxWebhooksException e) {
    System.out.println(e.getStatusCode());
    System.out.println(e.getMessage());
    System.out.println(e.getResponseBody());
}

A non-2xx response throws PauboxWebhooksException, which provides getStatusCode(), getUrl(), and getResponseBody(); its message includes the API’s error text. 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 throws before any request is sent, with getStatusCode() of 0. Every method is declared throws Exception, so call it from a method that declares or handles Exception. Network failures throw IOException, not PauboxWebhooksException. The data classes are in com.paubox.data.

Get started

Email API

Migrate to Paubox

Marketing API

MCP Server

SDKs

CLI

Forms API

Create the service

Events

List webhook endpoints

Create a webhook endpoint

Get a webhook endpoint

Update a webhook endpoint

Delete a webhook endpoint

Error handling

​Create the service

​Events

​List webhook endpoints

​Create a webhook endpoint

​Get a webhook endpoint

​Update a webhook endpoint

​Delete a webhook endpoint

​Error handling

Create the service

Events

List webhook endpoints

Create a webhook endpoint

Get a webhook endpoint

Update a webhook endpoint

Delete a webhook endpoint

Error handling