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 events in the REST API and JavaScript SDK 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 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.
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 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.
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.
- 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.