> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paubox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive real-time delivery event notifications from the Paubox Email API.

Paubox webhooks push delivery event notifications to an HTTPS URL you own. Configure them in the [Paubox Dashboard](https://next.paubox.com/emailapi/webhooks).

<Warning>
  **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.
</Warning>

## 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:

```json theme={null}
{
 "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](/email-api/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.

```
```