> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.fax.plus/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhook
## Definition
A **Webhook** is a mechanism that allows you to receive real-time notifications about faxes being sent and received.
## Setting Up Webhooks
To start receiving real-time updates, you need to create a webhook in the Fax.Plus system. Here's how:
1. Decide on a target URL where you want to receive webhook notifications. This should be an endpoint on your server that's set up to handle incoming POST requests.
2. Choose the event(s) you want to track. Fax.Plus offers the following webhook events:
* `fax_sent` — When a fax is successfully sent
* `fax_received` — When a fax is successfully received
* `fax_page_received` — When a single page of a fax is received (requires fax streaming, available on request)
3. Use the Fax.Plus API to create the webhook. You'll need to specify your target URL and the event(s) you want to track.
For detailed information on how to create a webhook using the API, refer to the [Register a
webhook](/api-reference/endpoints/webhooks/register-new-webhook) endpoint documentation.
## Handling Webhook Notifications
Once you've set up your webhook, Fax.Plus will send POST requests to your specified URL whenever the tracked events occur. Here's what you need to know about handling these notifications:
* **Request Method**: All webhook notifications are sent as HTTP POST requests.
* **Payload Structure**: The webhook payload is a JSON object containing two main sections:
* `hook`: Contains metadata about the webhook itself.
* `data`: Contains information about the fax that triggered the event.
## Events
### fax\_sent
The `fax_sent` event is triggered when a fax is successfully sent.
```json fax_sent payload theme={null}
{
"hook": {
"id": "66df09cf1d6d0b295c363956",
"event": "fax_sent",
"event_time": "2024-09-09 10:44:39",
"target": "https://webhook.com"
},
"data": {
"id": "66df09cf1d6d0b295c363956",
"uid": "490ae330dbc749f0b6561dafa300f2fb",
"pages": 1,
"from": "+1 334-304-xxxx",
"to": "+1 334-304-xxxx",
"start_time": "2024-09-09 10:44:39",
"file": "1d0b618e4fb54957878eed0ecc64ae5e.tiff",
"file_name": "fax-to-1334304xxxx",
"status": "success",
"cost": 1
}
}
```
If `hook.id` is not equal to `data.id`, the fax is being retried. If `hook.id` equals `data.id`, it indicates the fax
is being sent for the first time.
#### Payload schema
| Name | Type | Required | Description |
| :---------- | :---------- | :------- | :--------------------------------------------------------------------------- |
| **hook** | object | Yes | Hook and event description |
| id | `string` | Yes | Fax ID |
| event | `string` | Yes | Event type |
| event\_time | `string` | Yes | Time of the event. Format: YYYY-MM-DD HH:mm:ss |
| target | `string` | Yes | Configured URL target for this webhook |
| **data** | object | Yes | Callback data, depends on the event type |
| id | `string` | Yes | Fax session ID. This ID might differ from the one returned by listFaxes |
| uid | `string` | Yes | Sender user ID |
| pages | `number` | Yes | Number of pages in the fax |
| from | `string` | Yes | Sender number. Might be a user ID for faxes sent from free accounts |
| to | `string` | Yes | Fax destination number. Might be a user ID for faxes sent from free accounts |
| start\_time | `string` | Yes | Time at which faxing session started. Format: YYYY-MM-DD HH:mm:ss |
| file | `string` | Yes | File ID |
| file\_name | `string` | Yes | Human-readable file name |
| cost | `number` | Yes | Fax cost (in pages) |
| status | `FaxStatus` | Yes | Fax status |
### fax\_received
The `fax_received` event is triggered when a fax is successfully received.
```json fax_received payload theme={null}
{
"hook": {
"id": "9b0cfcad-5bf8-41ff-94f7-eb5b1b85a0bf",
"event": "fax_received",
"event_time": "2024-09-09 12:44:39",
"target": "https://webhook.com"
},
"data": {
"id": "9b0cfcad-5bf8-41ff-94f7-eb5b1b85a0bf",
"uid": "490ae330dbc749f0b6561dafa300f2fb",
"pages": 1,
"from": "+1 334-304-xxxx",
"to": "+1 334-304-xxxx",
"start_time": "2024-09-09 12:44:39",
"file": "27ade44579274f01b55e552cd361990e.tiff",
"file_name": "fax-from-1334304xxxx",
"status": "success",
"cost": 1
}
}
```
#### Payload schema
The payload schema for `fax_received` is identical to the `fax_sent` event.
### fax\_page\_received
The `fax_page_received` event is only available if your account has fax streaming enabled. This feature is available on request — contact us to discuss enabling it for your account.
The `fax_page_received` event is triggered when a single page of a fax is received. This event is only sent when fax streaming is enabled, allowing you to process pages as they arrive rather than waiting for the complete fax.
```json fax_page_received payload theme={null}
{
"hook": {
"id": "9b0cfcad-5bf8-41ff-94f7-eb5b1b85a0bf",
"event": "fax_page_received",
"event_time": "2024-09-09 12:44:39",
"target": "https://webhook.com"
},
"data": {
"id": "9b0cfcad-5bf8-41ff-94f7-eb5b1b85a0bf",
"page": 1,
"from": "+1 334-304-xxxx",
"to": "+1 334-304-xxxx"
}
}
```
#### Payload schema
| Name | Type | Required | Description |
| :---------- | :------- | :------- | :--------------------------------------------------------------------------- |
| **hook** | object | Yes | Hook and event description |
| id | `string` | Yes | Fax session ID |
| event | `string` | Yes | Event type |
| event\_time | `string` | Yes | Time of the event. Format: YYYY-MM-DD HH:mm:ss |
| target | `string` | Yes | Configured URL target for this webhook |
| **data** | object | Yes | Callback data for the page received event |
| id | `string` | Yes | Fax session ID |
| page | `number` | Yes | Page number that was received (starting from 1) |
| from | `string` | Yes | Sender number. Might be a user ID for faxes sent from free accounts |
| to | `string` | Yes | Fax destination number. Might be a user ID for faxes sent from free accounts |
### Verify origin IP addresses
To ensure that the webhook requests you receive are legitimate and originate from Fax.Plus, it’s important to verify the IP addresses.
Fax.Plus webhooks will only be sent from the following authorized IP addresses:
* 34.65.253.117
* 34.65.146.131
Make sure your server is configured to accept webhook requests only from these IPs to enhance security.
## Handling the Notification
When your server receives a webhook notification:
1. Verify the payload to ensure it's a valid webhook notification.
2. Extract the relevant information from the payload.
3. Perform any necessary actions based on the event type (e.g., update your database, notify users, trigger other processes).
4. Send a 200 OK response to acknowledge receipt of the webhook.
## Best Practices
* **Security**: Ensure your webhook endpoint is secure. Consider implementing authentication for your webhook URL.
* **Idempotency**: Design your webhook handler to be idempotent. This means it should produce the same result even if the same webhook is received multiple times.
* **Error Handling**: Implement robust error handling in your webhook processing logic.
By following this guide, you'll be able to set up and handle webhooks effectively, allowing your application to receive real-time updates about fax statuses in the Fax.Plus system.