Rust SDK webhook client

Webhook endpoint methods require SDK 2.0.0 or later. They are on paubox::webhooks::WebhooksClient, not on the PauboxClient you use to send email.

WebhooksClient 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 requires the webhooks feature (enabled by default).

Create the client

use paubox::webhooks::WebhooksClient;

let webhooks = WebhooksClient::new("YOUR_API_KEY");

WebhooksClient::with_base_url(api_key, url) overrides the base URL with a url::Url, and WebhooksClient::with_http(api_key, http) uses your own reqwest::Client. The client doesn’t read an environment variable. All methods are async and return Result<T, PauboxError>.

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

use paubox::webhooks::ListWebhookEndpointsParams;

let list = webhooks
    .list_webhook_endpoints(&ListWebhookEndpointsParams {
        page: Some(1),
        items: Some(50),
    })
    .await?;

for endpoint in &list.data {
    println!("{} {} {}", endpoint.id, endpoint.target_url, endpoint.status);
}
println!("{}", list.page_info.count);

Pass &ListWebhookEndpointsParams::default() for the first page. page_info.count is the total number of endpoints, not the length of data. Endpoints carrying an event the key isn’t scoped for are left out.

Create a webhook endpoint

let created = webhooks
    .create_webhook_endpoint(
        "https://example.com/webhooks/paubox",
        &["api_mail_log_delivered", "api_mail_log_opened"],
    )
    .await?;

println!("{}", created.endpoint.id);
println!("{}", created.signing_secret);

The target URL must be an https URL that doesn’t point at a private or internal address. create_webhook_endpoint returns a CreatedWebhookEndpoint, with the endpoint in endpoint and the secret in signing_secret. WebhookEndpoint has id (a UUID), target_url, status (active or disabled), events, created_at, and updated_at. The 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

let endpoint = webhooks
    .get_webhook_endpoint("2ec66c21-bf48-48eb-8d28-f80b2d6b77c7")
    .await?;

Update a webhook endpoint

use paubox::webhooks::UpdateWebhookEndpoint;

let updated = webhooks
    .update_webhook_endpoint(
        "2ec66c21-bf48-48eb-8d28-f80b2d6b77c7",
        UpdateWebhookEndpoint {
            status: Some("disabled".into()),
            ..Default::default()
        },
    )
    .await?;

UpdateWebhookEndpoint has optional target_url, status ("active" or "disabled"), and events fields. Only the fields you set are sent. events replaces the endpoint’s event list.

Delete a webhook endpoint

webhooks
    .delete_webhook_endpoint("2ec66c21-bf48-48eb-8d28-f80b2d6b77c7")
    .await?;

Error handling

use paubox::PauboxError;

match webhooks
    .create_webhook_endpoint("https://example.com/webhooks/paubox", &["api_mail_log_delivered"])
    .await
{
    Ok(created) => println!("{}", created.endpoint.id),
    Err(PauboxError::Http { status, body }) => eprintln!("{status}: {body}"),
    Err(PauboxError::Auth(message)) => eprintln!("401: {message}"),
    Err(e) => eprintln!("{e}"),
}

A 401 returns PauboxError::Auth; any other non-2xx response returns PauboxError::Http. Both carry 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 returns PauboxError::Validation 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