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

{
  "App Name": "Demo Shopify App",
  "Affiliate Name": "JohnDoe",
  "affiliateEmail": "[email protected]",
  "affiliatePromotingAgenda": ["Blog"],
  "Type": "JOIN_REQUESTED"
}

2. JOINED

{
  "App Name": "Demo Shopify App",
  "Affiliate Name": "JaneSmith",
  "affiliateEmail": "[email protected]",
  "Type": "JOINED"
}

3. REFERRAL

{
  "App Name": "Demo Shopify App",
  "Affiliate Name": "ReferralUser",
  "affiliateEmail": "[email protected]",
  "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.