Service Provider Interfaces (SPIs)

About SPIs

SPIs are APIs that are defined by Wix, which you can choose to implement.

By doing so, you will become a service provider. Wix will call your service during a certain flow, wait for your response, and then continue the flow with your response.

For example, a Local Delivery Provider application may implement the Restaurants Local Delivery SPI that includes a Get Delivery Estimate endpoint. This provider will be called to fetch applicable delivery estimates during a customer’s checkout flow.

Terminology

  • SPI - Service Provider Interface - The API specification that has to be implemented by Service Providers.
  • SPI Host - The Wix service that calls your application during one of its business flows.
  • Service Provider (a.k.a. implementer) - The application that implements the SPI.
  • Public Key - A key available to you in the Wix Developers Center to verify Wix’s request signatures.
  • Events - Asynchronous events sent from the service provider to the SPI host (the equivalent of an API call under other circumstances, and using the standard OAuth2 authorization).

Setup

In order to become a service provider, you have two options:

  • In the Wix Dev Center, add the extension you wish to implement as described below.
  • Become a service provider in a single site by implementing the SPI using Velo.

Configure an integration component in the Developers Center

In order to enable Wix to communicate with your app, add configurations for your extension:

  1. In the side menu under Build your app, click Extensions.

  2. In the upper right corner of the page, select Create Extension.

  3. Filter by tag, or search to find the extension you need.

  4. Select the relevant extension and click Create.

  5. In the JSON editor, configure the parameters by referencing the Documentation section on the right side of the page. For each parameter, add the parameter name and value in the JSON editor.

  6. Click Save.

Note: If you are working with a legacy SPI, configuration may not be via the Wix Developers Center. See instructions in the specific SPI.

Request envelope

As a Service Provider you are required to implement an API specification exactly as documented. Each request that your endpoints receive is wrapped in an envelope with some metadata and signed.

The payload that your endpoints receive are in JWT format, with the following structure:

Copy
1
{
2
  "data": {
3
    "request": {/*as specified in the SPI reference*/},
4
    "metadata": {/*as explained below*/}
5
  },
6
  "aud": "<your application's appId>",
7
  "iss": "wix.com",
8
  "iat": <issue timestamp>,
9
  "exp": <expiration timestamp>
10
}

The metadata in the envelope is common to all SPI endpoints, although some attributes will only appear in specific endpoints.

The envelope attributes are:

  • requestId - a unique identifier of the request. You may print this ID to your logs to help with future debugging and easier correlation with Wix' logs.
  • instanceId - The Service Provider App's instance ID.
  • currency - ISO 4217 3 letter currency code.
  • languages - a string that represents the country and language in which the response from the Service Provider is expected to be returned in concatenated ISO 639-1: 2 Alpha language-code and ISO 3166-1: 2 Alpha country-code format. E.g. en-US.
  • identity - An object that describes the identity that triggered this request, with the following structure:
Copy
1
{
2
  identityType: "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP
3
  anonymousVisitorId: "<anonymousVisitorId>",
4
  memberId: "<memberId>",
5
  wixUserId: "<wixUserId>",
6
  appId: "<appId>"
7
}

Validating request signatures

As explained above, the request payload is a signed JWT. In order to avoid an attack where a malicious 3rd party is sending you requests pretending to come from Wix, you MUST verify the JWT, as follows:

  • Verify the JWT signature using your public key from the Wix Developers Center.
  • Verify that the aud claim matches your application id.
  • Verify that the iss claim is set to wix.com.
  • Verify that the iat claim is set to a timestamp before current on your server.
  • Verify that the exp claim is set to a timestamp after the current timestamp on your server.

It is strongly recommended that you use a standard library to parse and validate the JWT. There are popular libraries for all popular languages. Check out official JWT site

Events

Some flows require you to send asynchronous events (webhooks) to the Wix SPI host server. These flows are documented in the SPI reference.To report an event, you must call the endpoint that appears in SPI reference, and send the required payload.

Was this helpful?
Yes
No