Go Headless

Build Apps

Client

API Preview

Develop Websites

REST

Velo

GraphQL (Alpha)

# 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 [Wix Dev Center](fallback::https://dev.wix.com/apps/my-apps), 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. Open your app in the [Dev Center](fallback::https://dev.wix.com/apps/my-apps).
1. In the side menu, click **Webhooks**.
1. Click  **+ Create Webhook**.
1. Select an **API Category**. For example, **eCommerce**.
1. Choose a webhook event from the available options. For example, **Order Canceled**.
1. Enter your server **Callback URL**. This is where Wix sends the event data.
1. Add the relevant **Permissions**.
1. 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)](fallback::https://jwt.io/) format. Your public key allows you to verify the signature in any webhook you receive. 

To get your public key:

1. Open your app in the [Dev Center](fallback::https://dev.wix.com/apps/my-apps).
1. In the side menu, click **Webhooks**.
1. Click **Get Public Key**.

    ![Get public key button](https://wixmp-833713b177cebf373f611808.wixmp.com/images/handle-events-with-webhooks-md_build-apps-portal_develop-your-app_api-integrations_events_assets_get-public-key-button.png)
  
1. 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](fallback::https://dev.wix.com/docs/sdk):

1. Set up an Express server to handle incoming webhook requests:
   
    ```javascript
    import express from "express";

    const app = express();
    ```

1. Create a [`WixClient`](fallback::https://dev.wix.com/docs/sdk/core-modules/sdk/wix-client) with the [`AppStrategy`](fallback::https://dev.wix.com/docs/sdk/core-modules/sdk/app-strategy). Our client is initialized with the [`orders`](portalId::b85dea5b-341b-493b-b99e-4d4ca12baaa2resourceId::ba5cb0c8-97ce-40b1-8b33-3f21de8523f7slug::setup*fallback::https://dev.wix.com/docs/sdk/backend-modules/ecom/orders/setup) module, which allows us to access webhooks related to order events:

    ```javascript
    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 },
    });
    ```

    <blockquote class="tip">
    
    __Tip:__ Find your app ID on the **OAuth** page of the [Dev Center](fallback::https://dev.wix.com/apps/my-apps).

    </blockquote>

1. Use the [`onOrderCanceled`](portalId::b85dea5b-341b-493b-b99e-4d4ca12baaa2resourceId::ba5cb0c8-97ce-40b1-8b33-3f21de8523f7slug::on-order-canceled*fallback::https://dev.wix.com/docs/sdk/backend-modules/ecom/orders/on-order-canceled) method to register a callback function to handle order cancellation events:

    ```javascript
    client.orders.onOrderCanceled((event) => {
        console.log(`onOrderCanceled event received with data:`, event);
        //
        // Handle your event here
        //
    });
    ```
    
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:

    ```javascript
    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"));
    ```

    <blockquote class="important">

    __Important:__
    You must return a 200 response upon successful receipt of the webhook.
    
    </blockquote>
  
Here's the complete code example:

```javascript
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);
  //
  // 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

* [Test a Webhook Locally](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/api-integrations/events-and-webhooks/test-a-webhook-locally)