Paubox webhooks push delivery event notifications to an HTTPS URL you own. Configure them in the Paubox Dashboard.
Organization-wide scope: Webhooks are triggered at the organization level. Events from all domains in your organization will be sent to the configured webhook URL; there is no per-domain filtering. Design your handler to inspect the from field in the payload if you need to route events by domain.
Webhook fields
- URL: You will need to provide an HTTPS URL which you own, to which you would like your webhook payload to be sent.
- Event: The events notifications to which you would like to subscribe
Available events
| Event Name | Event Name Key Value | Trigger |
|---|
| Delivered | api_mail_log_delivered | When message is delivered |
| Temporary Failure | api_mail_log_temporary_failure | On soft bounce of message |
| Permanent Failure | api_mail_log_permanent_failure | On hard bounce of message |
| Opened | api_mail_log_opened | On opening of message |
Payloads
Every Webhook notification will include an event_name key and a payload key. The type of payload you should expect is dependent on the data model that is triggering the webhook event.
The most common type of payload is the API Mail Log payload, which is structured as follows:
{
"event_name": "api_mail_log_permanent_failure",
"payload": {
"id": 5555555555,
"subject": "Hello from the Paubox Email API",
"header_message_id": "<XXX430aa-9b7c-42d5-9614-2e38f5a3f71f@XXXXXXXXX.com>",
"source_tracking_id": "XXXef39e-b376-4a44-b2b9-85bdb406dXXX",
"outbound_queue_id": "XXXyFY0y3Yz2XXX",
"time": "2022-04-18T20:27:25.379Z",
"from": "XXXXXX@XXXXXXX.com",
"to": "recipient@example.com",
"custom_headers": {
"X-Custom-Header": "value"
}
}
}
Retry behavior
Paubox does not currently retry failed webhook deliveries. If your endpoint is unavailable when an event fires, that notification will not be re-sent. Design your endpoint to be highly available, and use the Get message receipt endpoint to poll for status if you need guaranteed delivery tracking.
Verifying webhook signatures
Webhook signature verification is not currently supported. Use network-level controls (e.g., IP allowlisting or a shared secret in the URL path) to validate that requests to your endpoint originate from Paubox.
