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. Explore all events in the REST API reference and app-level events specifically in the App Instances API.
Webhook payloads
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 Wix Dev Center.
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.
-
Duplicate events: To minimize the risk of data loss and ensures 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.
Tip: The Webhooks page of the Dev Center features a Logs tab where you can view a comprehensive list of all webhooks sent to your servers.
Best practices
- Send a status 200 response upon receipt of a webhook
- Update webhooks as soon as possible, as outdated webhooks can prevent apps from working correctly
- 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