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.

• API Key — create and manage the Shoffi API Key used to authenticate calls to the Shoffi API.

---

Webhook tab

Creating a new integration

1. Navigate to the Integrations page

   • In your Shoffi dashboard, click Integrations in the left-hand menu.

   • 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 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

   • 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

{
  "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.

---

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