Webhooks
An introduction to webhooks
- A webhook is like a reverse API endpoint
- Instead of sending the API a "GET" request to get the status of something, a webhook allows the customer to subscribe to notifications, sent via "POST", that are triggered by predetermined events
- Webhooks are currently available to our Paubox Email API customers
- Paubox webhooks support endpoints which use the HTTPS protcol, on connections which use TLS 1.2 and above
Why use webhooks?
- Webhooks are useful because they allow users to receive instant updates whenever the subscribed event is triggered
- This can help with such things as:
- Providing real-time status updates for custom analytics
- Custom alerts
- Automating workflows
How to use webhooks
- Click the 'Webhooks' link in the left-hand navigation menu, in the API section
- Click the 'Add new webhook' button to bring up the webhook form modal
- Webhooks are currently triggered at an organization-wide level. This means that events for all domains your organization has set up with Paubox will trigger a webhook notification.
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 |
* Webhook for open-tracking event is currently in beta
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": "XXXXXXX@XXXXXXX.com"
}
}