wix-webhooks

Wix Webhooks

When to Use This Skill

• How do I receive Wix webhooks in a self-hosted app?
• How do I verify Wix webhook signatures (the JWT)?
• Where do I get my Wix public key to verify webhooks?
• How do I handle wix.ecom.v1.order_created / order_approved / order_canceled events?
• Why is my Wix webhook JWT verification failing?

How Wix Webhooks Work

Wix delivers each webhook as an HTTP POST whose entire request body is a signed JWT (RS256), signed by Wix. There are no X-Wix-Signature/HMAC headers and it is not Standard Webhooks — verification means validating the JWT with your app's public key.

• Get your public key from the app dashboard → Custom Apps → your app → Webhooks → "Get Public Key" (also under View ID & keys). It is per-app; there is no global JWKS endpoint.
• Verify against the raw, unparsed body. Re-serializing the JSON breaks the signature.
• The decoded JWT is a nested envelope: outer { data, iat, exp } → data is a JSON string → parse it to { eventType, instanceId, data } → parse the inner data string to get the entity/event payload.

Verification (core)

Node.js — official @wix/sdk verifies (RS256, via jose) and decodes in one call. Pass the raw text body:

import { AppStrategy, createClient } from '@wix/sdk';
import { orders } from '@wix/ecom';

const client = createClient({
  auth: AppStrategy({
    appId: process.env.WIX_APP_ID,
    publicKey: process.env.WIX_PUBLIC_KEY.replace(/\\n/g, '\n'), // PEM, or base64-encoded PEM
  }),
  modules: { orders },
});

// Register typed handlers up front...
client.orders.onOrderCanceled((event) => {
  console.log('Order canceled', event.metadata.entityId, 'event', event.metadata._id);
});

// ...then verify + dispatch the raw JWT body (throws if the signature/exp is invalid):
await client.webhooks.process(rawBody);

Python (no official server SDK) — verify the JWT manually with PyJWT + your public key:

import json, jwt  # PyJWT

def verify_and_decode(raw_body: bytes, public_key: str) -> dict:
    decoded = jwt.decode(raw_body, public_key, algorithms=["RS256"])  # raises on bad signature/exp
    event = json.loads(decoded["data"])          # -> { eventType, instanceId, data: "<json>" }
    event["entity"] = json.loads(event["data"])  # inner event/entity payload (has id, entityId, ...)
    return event