> Portal Navigation:
>
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt
## Resource: About Webhooks
## Article: About Webhooks
## Article Link: https://dev.wix.com/docs/build-apps/develop-your-app/api-integrations/events-and-webhooks/about-webhooks.md
## Article Content:
# About Webhooks
Webhooks are triggered by real-time events relevant to your app and the sites where your app is installed. Rather than continuously polling the status of the app or site through periodic API calls, webhooks enable your app to execute code directly in response to events. For example, you can trigger an action when a site admin creates a new product or a site visitor pays for their order.
> **Notes:**
>
> - When building apps using Blocks, [handle events using Velo](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/backend-code/events/about-backend-events.md) instead of webhooks.
> - When building apps using the CLI, you can also handle events using [event extensions](https://dev.wix.com/docs/wix-cli/guides/extensions/backend-extensions/events/add-event-extensions.md).
Webhook events cover site operations like product creation and purchases, along with app-related actions such as installation or plan upgrades. You can explore events in the [API Reference](https://dev.wix.com/docs/api-reference.md). The documentation sidebar lists events alongside their related API methods.
## Handle webhooks with the Wix CLI
To handle webhooks with the [Wix CLI](https://dev.wix.com/docs/wix-cli/guides/about-the-wix-cli.md), use [event extensions](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/events/about-event-extensions.md). The Wix CLI handles webhook payloads automatically.
## Handle webhooks with self-hosting
To handle webhooks in a [self-hosted](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/about-self-hosting-for-wix-apps.md) app, you need to handle the webhook payload directly in your code.
Event data is sent as a [JSON web token (JWT)](https://jwt.io/) in the body of the webhook request. The JWT is signed, allowing you to verify its authenticity as originating from Wix. To verify the token, use your public key from the Webhooks page of the [app dashboard](https://manage.wix.com/account/custom-apps).
The JavaScript SDK offers a `process` method on the [`WixClient`](https://dev.wix.com/docs/sdk/core-modules/sdk/wix-client.md) for verifying and decoding the JWT. For an example, see [Handle Events With Webhooks](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/webhooks/handle-events-with-webhooks-for-self-hosting-using-the-java-script-sdk.md).
Once verified and parsed, every webhook includes the following properties:
* `instanceId`: The unique identifier of your app within the site.
* `eventType`: A description of the webhook event.
The rest of the webhook data differs depending on the specific event.
> **Note:** Webhooks don’t always return the full entity. For example, some legacy webhooks only return fields that were updated as the result of the event. In such cases, you may need to make a GET request to the related entity endpoint.
## Event delivery and redundancy
Webhook behavior can become complex in certain situations:
* **Delayed or out of order events:** If your server fails to respond with a 200 status code within 1250 ms, additional attempts will be made to deliver the event to your app. This delay could cause subsequent events to be received before earlier ones. Resent webhooks always include the data from the time of the event. For more information, see the [Webhook Resend Policy](#resend-policy).
* **Delayed webhooks:** In rare cases, webhooks may arrive later than their original timestamp.
* **Duplicate events:** To minimize the risk of data loss and ensure continuity of events, multiple copies of your app events are stored on different servers. However, if a server holding a copy is inaccessible at the time of event delivery, you might receive the same event multiple times. We recommend designing your app to handle duplicate events. You can store processed event IDs and check against them before processing new webhooks to ensure you don't process the same event multiple times.
__Tip:__ The Webhooks page of your app's dashboard features a **Logs** tab where you can view a comprehensive list of all webhooks sent to your servers.
## Resend policy
A webhook can fail due to a timeout error (1250 ms) or if a 200 status code isn't received. In case of failure, up to 12 additional attempts are made to send the webhook based on the following retry schedule:
| Attempt | Time |
|--|--|
| 1 | 1 minute after failure |
| 2 | 10 minutes after previous failure |
| 3 | 1 hour after previous failure |
| 4 | 2 hours after previous failure |
| 5 | 2 hours after previous failure |
| 6 | 2 hours after previous failure |
| 7 | 4 hours after previous failure |
| 8 | 4 hours after previous failure |
| 9 | 4 hours after previous failure |
| 10 | 8 hours after previous failure |
| 11 | 8 hours after previous failure |
| 12 | 12 hours after previous failure |
> **Note:** Resending webhooks doesn't affect future webhooks sent to the same endpoint. Therefore, it's possible to receive webhooks out of order if a resent webhook arrives after a webhook that was successfully delivered on the first attempt.
## Webhooks and versioning
Webhooks are versioned like any other app extension:
- Adding a webhook creates a new minor version of your app. Minor versions are automatically pushed to users on the latest major version, so those users receive the new webhook right away.
- Sites on older major versions won't trigger the new webhook until the site owner updates to the latest major version.
**Important:** Because sites on older major versions don't receive new webhooks, encourage your users to keep your app up to date. You can include a call to action within your app prompting users to update, redirecting them to `https://wix.com/app-installer?appId={YOUR_APP_ID}`.
For more information about how versioning works, see [About App Versioning](https://dev.wix.com/docs/build-apps/manage-your-app/versioning/about-app-versioning.md).
## Best practices
* Send a status 200 response upon receipt of a webhook.
* Make periodic API requests to confirm webhooks are being received and are accurate to the status of your app or site.
* Ensure your server can handle out-of-order and duplicate webhooks.
* Store processed event IDs and check against them before processing new webhooks to ensure you don't process the same event multiple times.
* Update webhooks as soon as possible. Look for alerts on outdated webhooks on the **Webhooks** page of your app's dashboard. The alert contains information on how to update the webhook. Outdated webhooks can disrupt app functionality.
* Regularly check for updates to your app, and install the latest version to prevent potential issues with webhook functionality.
## See also
* [Handle Events With Webhooks](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/webhooks/handle-events-with-webhooks-for-self-hosting-using-the-java-script-sdk.md)
* [Test a Webhook Locally](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/webhooks/test-a-webhook-locally-for-self-hosting.md)