> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Add Self-hosted Service Plugin Extensions with REST

## Article: Add Self-hosted Service Plugin Extensions

## Article Link: https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-rest.md

## Article Content:

# Add Self-hosted Service Plugin Extensions with REST

Add a [service plugin](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/service-plugins/about-service-plugin-extensions.md) (formerly SPI) extension to your app in your [app's dashboard](https://manage.wix.com/account/custom-apps) to extend the functionality of a Wix site.  

With service plugins, your app can:
+ **Inject custom logic into existing Wix app flows:** For example, a typical eCommerce checkout process does not allow a site owner to add additional fees that are unrelated to specific line items. Your app can use the [Additional Fees service plugin](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/additional-fees/additional-fees-service-plugin/introduction.md) to add extra fees, like gift wrap charges or a fee for fragile items, to the Wix Checkout flow.
+ **Introduce entirely new flows to Wix sites:** For example, when a site owner sets up a Wix store, there are a limited number of payment and shipping rates service providers to choose from. Your app can use the [Shipping Rates service plugin](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/shipping-rates/shipping-rates-integration-service-plugin/introduction.md) to offer additional 3rd-party shipping rates providers currently unavailable to Wix sites.

## Before you begin

It's important to note before getting started that your implementation must match the API specification exactly as documented. 
This ensures that as a service provider, Wix can use your response in its flow. 

This integration includes the request envelope and signature validation as follows: 

### Request envelope

Each request that your endpoint receives is wrapped in an envelope with metadata and signed.

The payload that your endpoint receives is in [JSON web token (JWT)](https://jwt.io/introduction/) format, with the following structure:
```json
{
  "data": {
    "request": {/*as specified in the service plugin reference*/},
    "metadata": {/*as explained below*/}
  },
  "aud": "<your application's appId>",
  "iss": "wix.com",
  "iat": <issue timestamp>,
  "exp": <expiration timestamp>
}
```

The `metadata` in the envelope is common to all service plugin endpoints, although some attributes may only appear in specific endpoints.

The envelope attributes are:

- `requestId`: Unique identifier of the request. You may print this ID to your logs to help with future debugging and easier correlation with Wix's logs.
- `instanceId`: Service provider app's instance ID.
- `currency`: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-letter currency code.
- `languages`: 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](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) and [ISO 3166-1: 2 Alpha country-code](https://en.wikipedia.org/wiki/ISO_3166-1) format, such as `"en-US"`.
- `identity`: Object that describes the identity that triggered this request, with the following structure:
    - `identityType`: Type of site visitor making the request. Possible values:
      - `ANONYMOUS_VISITOR`
      - `MEMBER`
      - `WIX_USER`
      - `APP`
    - `anonymousVisitorId`: ID of the anonymous site visitor (if applicable).
    - `memberId`: ID of the site member (if applicable).
    - `wixUserId`: ID of a Wix user (if applicable). 
    - `appId`: ID of an app (if applicable).  


### Validating request signatures

As explained above, the request payload is a signed JWT. 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](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/webhooks/handle-events-with-webhooks-for-self-hosting-using-the-java-script-sdk.md) from your app's dashboard.
- 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_ the current timestamp on your server.
- Verify that the `exp` claim is set to a timestamp _after_ the current timestamp on your server.

We recommend that you use a standard library to parse and validate the JWT. There are libraries available for all popular languages. Check out the [official JWT site](https://jwt.io/libraries).

## Add a service plugin to your app
Follow these steps to add a service plugin to your app.

1. Select an app from the [Custom Apps page](https://manage.wix.com/account/custom-apps) in your Wix Studio workspace. 

1. Go to the Extensions page, and click **+ Create Extension**.

   ![Create extension](https://wixmp-833713b177cebf373f611808.wixmp.com/images/19c148e0783a374c3da242e7a33c0cce.png)

1. Filter by tag, or search to find the extension you want to add.

1. Select the relevant extension and click **+ Create**.

1. 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.

   ![screenshot of json editor](https://wixmp-833713b177cebf373f611808.wixmp.com/images/5ac20a0893bef135b62812157515b7bd.png)

6. Click **Save**.

> **Note:**
> For some legacy service plugins, configuration might be managed elsewhere. Refer to the documentation of the specific service plugin you are implementing for instructions.

## Events
Some flows require you to send asynchronous events (webhooks) to Wix. These flows are documented in the service plugin reference. For an example, see the [Payment Service Provider service plugin](https://dev.wix.com/docs/rest/business-management/payments/service-plugins/payment-service-provider-service-plugin/webhooks.md).

To report an event, you must call the endpoint that appears in the service plugin reference and send the required payload. 

### Authorization
Every call must include an `Authorization` header with an access token as its value.  

Before you can obtain an access token, your app must have the appropriate permissions. To get these permissions, contact the Wix team mentioned in the specific documentation and confirm that your app has the necessary permission.

To obtain an access token, send a `POST` request to this endpoint:
```bash
https://www.wixapis.com/oauth/access
```
Include this header:
```bash
Content-Type: application/json,
```
The body of the request must be a JSON object with following format:
```json
{
  "grant_type" : "client_credentials",
  "scope" : "CASHIER.GET_ACCESS",
  "client_id" : <APP_ID>,
  "client_secret" : <APP_SECRET_KEY>
}
```
You can [find your app ID and secret key](https://manage.wix.com/app-selector?title=Select+an+App&primaryButtonText=Select+Site&actionUrl=https%3A%2F%2Fdev.wix.com%2Fapps%2F%7BappId%7D%2Foauth) in the **OAuth** page in your app's dashboard.

The response to the request has a body with the following format:
```json
{
  "refresh_token": null,
  "access_token" : <ACCESS_TOKEN>
}
```
Use the value for `access_token` as the value for the `Authorization` header in your event requests.

> **Notes:**
> * Don't cache access tokens. Obtain a new one for each webhook you send.
> * These access tokens are only valid for the specific service plugin. You can't use them for other Wix APIs.
> * Access tokens retrieved using different `"grant_type"` values can't be used to send webhooks.

## See also

- [Tutorial | Create a Self-Hosted App](https://dev.wix.com/docs/build-apps/get-started/quick-start/create-a-self-hosted-app.md)
- [Tutorial | Set Up an App With the App Dashboard](https://dev.wix.com/docs/build-apps/get-started/tutorials/tutorial-set-up-an-app-with-the-app-dashboard.md)