# Webhooks guide

# Webhooks

Webhooks let you receive real-time event notifications from Praxedo instead of polling the API. This feature is currently in **Beta**.

> info
> Before using webhooks, please contact our Customer Care team (support@praxedo.com) or your Account Manager.

## Managing subscriptions

Subscriptions are managed through the `Webhooks` endpoints below (create, list and delete a subscription). A few rules apply:

- You can create up to 3 subscriptions per OAuth 2.0 application.
- Subscriptions cannot be modified once created — to change a callback URL (e.g. from staging to production), create a new subscription.
- You only receive notifications from the office and sub-offices associated with your OAuth 2.0 application.

See [Configuring your OAuth 2.0 application](https://support.praxedo.com/hc/en-us/articles/16700630262162-Configuring-your-OAuth-2-0-application) to set up the application your subscriptions will be attached to.

## Event delivery

Once a subscription is active, matching events are sent as JSON to your callback URL. The payload and headers for each event type are documented in the Webhooks section below.

**Retry policy**

- Acknowledge every callback with a `200` status within 5 seconds, or a retry will be triggered.
- Automatic retries use an exponential back-off, up to a 10-minute interval between attempts.
- Retries stop after 1 hour of attempts for a given event.
- Because retries can occur, the same event may be delivered more than once. Acknowledge immediately and process the notification asynchronously, and make your handler idempotent (for example, de-duplicate on the callback's `id` field).

**Subscription policy**

- During the Beta phase, subscriptions are not automatically disabled, but this will change for callback servers that continuously error.
- Praxedo may delete a subscription that causes system stress. When this happens, all data for that subscription and its event history are permanently deleted and cannot be recovered.

## Headers

Each callback request includes standard infrastructure headers plus the following:

| Header | Description |
| --- | --- |
| `x-praxedo-event` | The event type carried by this callback (e.g. `workorder.deletion`). |
| `x-praxedo-secret` | The custom security header defined when the subscription was created, used to verify the callback's authenticity. `null` if none was set. |

Any custom headers you configured at subscription creation are also included as-is.

## Service Level Agreement

- **Uptime**: Praxedo guarantees 99.9% monthly uptime for the webhooks service, excluding scheduled maintenance.
- **Client responsibility**: you are responsible for the uptime and accessibility of your callback URL. Praxedo attempts delivery for up to 1 hour and is not responsible for data loss once that retry window has expired.
- **Traceability**: delivered events are stored and traceable for 15 days in case of delivery failure.
- **Support**: contact support@praxedo.com with your subscription ID and a description of the issue. Support is available 9:00 AM–5:00 PM CET, Monday to Friday, with an initial response to critical issues within 24 hours.

Note: This is a Beta version — features, endpoints and payloads may change before general availability.