Handle Events With Webhooks

To handle events with webhooks, you need to subscribe to the webhook and create a webhook handler. When you subscribe to a webhook in the 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. Select an app from the Custom Apps page in your Wix Studio workspace.
  2. In the side menu, click Webhooks.
  3. Click + Create Webhook.
  4. Select an API Category. For example, eCommerce.
  5. Choose a webhook event from the available options. For example, Order Canceled.
  6. Enter your server Callback URL. This is where Wix sends the event data.
  7. Add the relevant Permissions.
  8. Click Subscribe.

Your app is set up to receive the webhook.

Step 2 | Save 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.

To get your public key:

  1. Select your app from the Custom Apps page in your Wix Studio workspace.

  2. In the side menu, click Webhooks.

  3. Click Get Public Key.

    Get public key button

  4. 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 using the JavaScript SDK:

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

    Copy
    import express from "express"; const app = express();
  2. Create a WixClient with the AppStrategy. Our client is initialized with the orders module, which allows us to access webhooks related to order events:

    Copy
    import { AppStrategy, createClient } from "@wix/sdk"; import { orders } from "@wix/ecom"; const PUBLIC_KEY = `<YOUR_PUBLIC_KEY>`; const APP_ID = "<YOUR_APP_ID>"; const client = createClient({ auth: AppStrategy({ appId: APP_ID, publicKey: PUBLIC_KEY, }), modules: { orders }, });

    Tip: Find your app ID on the OAuth page of your app's dashboard.

  3. Use the onOrderCanceled method to register a callback function to handle order cancellation events:

    Copy
    client.orders.onOrderCanceled((event) => { console.log(`onOrderCanceled event received with data:`, event); console.log(`App instance ID:`, event.metadata.instanceId); // // Handle your event here // });

Note: You get the app instance ID in the webhook metadata. Learn more about app instances.

  1. Define a POST endpoint /webhook on your Express server to receive incoming webhook payloads. Within the endpoint, process the incoming webhook payload using the process method provided by the SDK:

    Copy
    app.post("/webhook", express.text(), async (request, response) => { try { await client.webhooks.process(request.body); } catch (err) { console.error(err); response .status(500) .send(`Webhook error: ${err instanceof Error ? err.message : err}`); return; } response.status(200).send(); }); app.listen(3000, () => console.log("Server started on port 3000"));

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

Here's the complete code example:

Copy
import express from "express"; import { AppStrategy, createClient } from "@wix/sdk"; import { orders } from "@wix/ecom"; const app = express(); const PUBLIC_KEY = `<YOUR_PUBLIC_KEY>`; const APP_ID = "<YOUR_APP_ID>"; const client = createClient({ auth: AppStrategy({ appId: APP_ID, publicKey: PUBLIC_KEY, }), modules: { orders }, }); client.orders.onOrderCanceled((event) => { console.log(`onOrderCanceled event received with data:`, event); console.log(`App instance ID:`, event.metadata.instanceId); // // Handle your event here // }); app.post("/webhook", express.text(), async (request, response) => { try { await client.webhooks.process(request.body); } catch (err) { console.error(err); response .status(500) .send(`Webhook error: ${err instanceof Error ? err.message : err}`); return; } response.status(200).send(); }); app.listen(3000, () => console.log("Server started on port 3000"));

See also

Did this help?