Handle Events with Webhooks for Self-hosting Without the JavaScript SDK

To handle events with webhooks, you need to subscribe to the webhook and create a webhook handler. When you subscribe to a webhook in your app dashboard, you specify the endpoint where Wix should send webhook data. Then, when the event occurs, Wix sends a POST request to your handler containing event data and proceeds based on your response.

This article outlines the process of subscribing to and processing the order canceled webhook from Wix eCommerce.

Step 1 | Subscribe to a webhook

To subscribe to a webhook:

1. Go to the Webhooks page in your app's dashboard.

2. Click + Create Webhook.

3. Select an API Category. For example, eCommerce.

4. Choose a webhook event from the available options. For example, Order Canceled.

   Tip: A simple code sample is provided that you can use to set up a server that handles the event. See Step 3 for more information on handling the event.

   Your public key is provided in the code sample. Even if you don't use the code sample, save the public key in a secure location for use later in this flow.

5. Enter your server Callback URL. This is where Wix sends the event data.

6. Add the relevant Permissions.

7. Click Subscribe.

Your app is set up to receive the webhook.

Step 2 | Retrieve your public key

Webhook payloads are sent in JSON web token (JWT) format. Your public key allows you to verify the signature in any webhook you receive.

Your public key was provided in the code sample in step 1, but if you need to retrieve it again, it's available on your app's home page under View ID and Keys:

Save the public key in a secure location.

You need to use this public key in your handler to verify that the request is from Wix.

Step 3 | Handle the event

The following steps demonstrate how to handle a webhook event.

1. Set up an Express server to handle incoming webhook requests:

   Install the express package:

   Copy

   Then add the following code:

   Copy

2. Install the jsonwebtoken package, which we use to verify the request.

   Copy

   Then add the following code:

   Copy

3. Define a POST endpoint /webhook on your Express server to receive incoming webhook payloads.

   Copy

   Important: You must return a 200 response upon successful receipt of the webhook.

4. Within the endpoint, verify the token and then handle incoming webhook payloads, specifically the payload from your event. For details about the payload, see Webhook Structure.

   Copy

   Note: The app instance ID is sent along with the event data. Learn more about app instances.

Here's the complete code example:

See also

• Test a Webhook Locally
• Webhook Structure