> For the complete documentation index, see [llms.txt](https://docs.shoffi.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shoffi.app/for-app-owners/integrations-webhooks.md).

# Integrations (Webhooks & API Key)

### Overview

The **Integrations** page has two tabs:

* **Webhook** — receive real-time notifications about important events in your app by sending event data to any publicly accessible URL. Webhooks are available on the **Growth** plan and above.
* **API Key** — create and manage the Shoffi API Key used to authenticate calls to the [Shoffi API](/the-shoffi-api/introduction-to-shoffi-api.md).

If you move to a plan without Integrations, Shoffi keeps any webhooks you already saved but does not send events until Integrations is available again.

***

## Webhook tab

### Creating a new integration

1. **Navigate to the Integrations page**
   * In your Shoffi dashboard, click **Integrations** in the left-hand menu. App owners and Editors (write permission) can open this page; Viewers cannot.
   * Open the **Webhook** tab.
   * A list of existing integrations is displayed, each with details such as the integration name, linked app, notifications count, and actions (**Edit**, **Delete**).
2. **Add a new integration**
   * Click **Add Integration** at the top-right corner of the Integrations page.
   * A modal titled **New Integration** will appear.
3. **Fill in the integration details**
   * **Integration Name**: A name that helps you identify this webhook (e.g., “Subscription-Only Events”).
   * **Webhook URL**: A publicly accessible **https** URL where Shoffi will send the webhook events (e.g., `https://example.com/webhook`). Use a public domain name — not an IP address, and not `http://`.
   * **App**: The app this webhook integration will be associated with (e.g., “RTL Master,” “RTL King: Hebrew,” etc.).
   * **Types**: Check which event types you want to receive (e.g., `affiliates/join_requested`, `affiliates/joined`, `affiliates/referral`, etc.).
4. **Validate your webhook**
   * Click **Validate Webhook**. Shoffi will send a sample request to the provided URL.
   * If Shoffi receives a `2xx` response, validation succeeds, and you can proceed.
   * The **Save** button is enabled only after successful validation.
5. **Save the integration**
   * After validation is successful, click **Save** to finalize the integration.
   * The new integration appears in the **Integrations** list.

***

### How webhooks work

When an event occurs, Shoffi sends an HTTP POST request to your specified **Webhook URL**. Each request includes:

* `Type`: A string identifying the event type (e.g., `JOIN_REQUESTED`, `JOINED`, `REFERRAL`, etc.).
* Relevant data fields: A JSON payload with details about the event, such as affiliate name, email, and date/time.

***

### Event definitions

* **affiliates/join\_requested**\
  Occurs when someone applies to become an affiliate. This event is sent only if your app requires manual approval.
* **affiliates/joined**\
  Occurs when an affiliate is officially approved or confirmed, and they can now start promoting.
* **affiliates/referral**\
  Occurs when an affiliate successfully refers someone to your store or product. This event carries information about the referral.
* **affiliates/referral\_requested**\
  Occurs when an affiliate manually requests credit for a specific referral.
* **affiliates/payment\_requested**\
  Occurs when an affiliate requests a payout for their accrued earnings.

***

### Example payloads

Below are three sample webhook payloads. All other event types use a similar structure, but with different fields as necessary.

#### 1. JOIN\_REQUESTED

```json
{
  "App Name": "Demo Shopify App",
  "Affiliate Name": "JohnDoe",
  "affiliateEmail": "john@example.com",
  "affiliatePromotingAgenda": ["Blog"],
  "Type": "JOIN_REQUESTED"
}

```

#### 2. JOINED

```json
{
  "App Name": "Demo Shopify App",
  "Affiliate Name": "JaneSmith",
  "affiliateEmail": "jane@example.com",
  "Type": "JOINED"
}
```

#### 3. REFERRAL

```json
{
  "App Name": "Demo Shopify App",
  "Affiliate Name": "ReferralUser",
  "affiliateEmail": "referraluser@example.com",
  "shopName": "demostore.myshopify.com",
  "Type": "REFERRAL"
}
```

***

### Webhook URL requirements

* Must start with `https://`.
* Must be a public domain name (not an IP address and not localhost).
* Must accept HTTP POST and return a `2xx` response when Shoffi sends the validation request and later event payloads.

### Slack incoming webhooks

You can paste a Slack **Incoming Webhook** URL (`https://hooks.slack.com/services/...`) directly into Shoffi. Slack only displays the `text` field in the channel, so for Slack URLs Shoffi puts the event JSON into `text` (for example `{"type":"REFERRAL","appName":"Demo App",...}`). Other webhook URLs keep the same JSON as before (no extra `text` field).

If you want more control over the Slack message (formatting, which fields appear, routing by event type), use **Zapier** instead: Catch Hook in Shoffi, then a Slack action in the Zap.

### Receiving and responding to webhook requests

1. **Set up a server endpoint**
   * Ensure the **Webhook URL** is an endpoint in your system that can accept and parse HTTP POST requests.
2. **Parse the payload**
   * Check the `Type` field to determine which event occurred.
   * Access other fields for event-specific information.
3. **Return a `2xx` response**
   * Return `200 OK` (or another `2xx` status) to indicate that you have successfully received the webhook.

***

### Event types

All currently available event types are:

* `affiliates/join_requested`
* `affiliates/joined`
* `affiliates/referral`
* `affiliates/referral_requested`
* `affiliates/payment_requested`

Each event’s JSON structure follows a pattern similar to the examples shown.

### Connecting to third-party tools

You can integrate Shoffi’s webhooks with external platforms like **Zapier**, **HubSpot**, and more:

* **Zapier**
  1. Create a new Zap and select **Webhooks by Zapier** as your trigger app.
  2. Choose **Catch Hook** as the trigger event.
  3. Copy the webhook URL Zapier provides and paste it into the **Webhook URL** field when creating or editing your Shoffi integration.
  4. Select the event types you want to receive and validate.
  5. Once set up, you can use the incoming webhook data within Zapier to connect to other apps, including **Slack** (add a Slack action such as **Send Channel Message**). You can also paste a Slack Incoming Webhook URL directly into Shoffi if you do not need Zapier.
* **HubSpot**
  1. In HubSpot, create a workflow or a custom integration that accepts inbound webhooks.
  2. Provide HubSpot’s webhook endpoint URL when setting up your Shoffi integration.
  3. Validate the webhook and save the integration.
  4. HubSpot will then receive real-time data from Shoffi, allowing you to automate processes or update contacts based on affiliate events.

In the same manner, any other tool that can accept inbound webhooks can be integrated by supplying the relevant endpoint URL in your Shoffi integration settings.

***

## API Key tab

Use the **API Key** tab to create a Shoffi API Key for each of your apps. This key authenticates requests to the [Shoffi API](/the-shoffi-api/introduction-to-shoffi-api.md). It is **not** the key used for the post-install request under `My Apps` → `Edit app`.

The Shoffi API is available on the Pro and Enterprise plans, so creating a key requires one of those plans.

### Create a key

1. Open **Integrations** → **API Key**.
2. Find the app in the list and click **Create key**.
3. Confirm, then **copy the key immediately**. For security, the full key is shown only once.
4. Store the key somewhere safe. Anyone with it can call the Shoffi API for that app.

### Rotate or revoke a key

* **Rotate** creates a new key and immediately invalidates the previous one. Update any integrations that still use the old key.
* **Revoke** deletes the key with no replacement. API calls using that key stop working until you create a new one.

The table shows a masked version of the current key (for example `sk_1a2b...9f8e`), when it was created, and when it was last used.