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.

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. The documentation sidebar lists events alongside their related API methods.

Handle webhooks with the Wix CLI

To handle webhooks with the Wix CLI, use event extensions. The Wix CLI handles webhook payloads automatically.

Handle webhooks when self-managing

To handle webhooks when self-managing, you need to handle the webhook payload directly in your code.

Event data is sent as a JSON web token (JWT) 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.

The JavaScript SDK offers a process method on the WixClient for verifying and decoding the JWT. For an example, see Handle Events With Webhooks.

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.

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.

• 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.

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

Webhooks and versioning

When you add a webhook, remove one, or update one, for example by editing its callback URL, you must release a new version of your app for the changes to take effect on the sites where your app is installed. Before you release, your app's dashboard shows them as unreleased changes.

The following table shows when changes take effect on the sites where your app is installed, depending on the version each site has when you release:

Site's installed app version	When changes take effect
Latest major version	If you release a minor version, changes take effect automatically. If you release a major version, changes take effect after a Wix user updates your app.
Older major version	Changes take effect after a Wix user updates your app to the latest major version.

Until the changes take effect on a site, the site keeps its previous webhook setup. For example, if you add a webhook, the site doesn't trigger it yet.

If you update a webhook's callback URL, Wix keeps sending events from sites that don't have the change yet to the previous callback URL. Keep the previous callback URL working for as long as any site uses it.

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
• Test a Webhook Locally