# Integrations (Webhooks)

### Overview

The Integrations (Webhooks) feature allows you to receive real-time notifications about important events in your app. By creating a webhook integration, you can send event data to any publicly accessible URL. This enables you to automate tasks, trigger external workflows, or synchronize Shoffi events with your external services.

***

### Creating a New Integration

1. **Navigate to the Integrations Page**
   * In your Shoffi dashboard, click **Integrations** in the left-hand menu.
   * 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 URL where Shoffi will send the webhook events (e.g., `https://example.com/webhook`).
   * **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 (Required)**
   * 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 (e.g., affiliate name, email, date/time).

***

### Event Definitions

* **affiliates/join\_requested**\
  Occurs when someone applies to become an affiliate. Only if your app requires manaul approval for affiliates.
* **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"
}
```

***

### 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.
* **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.