> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.hoppyapps.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 🔗 Integrate PopUps via Webhooks

Webhooks let you send popup submission data to any external URL in real time. This is perfect for connecting Hoppy PopUps with custom systems, CRMs, notification services, or any platform that accepts HTTP requests.

Every time a visitor submits a popup form, the app sends a JSON payload to your configured webhook endpoint — instantly and automatically.

---

# **⚠️ Before You Begin**

Before setting up webhooks, make sure:

* The **Hoppy PopUps** app is installed on your Shopify store  
* You have a **webhook URL** ready to receive data (from your developer, CRM, or third-party service)

No API keys or external accounts are required within the app — just a valid HTTPS endpoint.

---

# **🛠️ Step 1 — Open the Integrations Section**

Open the **Hoppy PopUps** app from your Shopify Admin.

Then:

→ Click the **Integrations** tab from the left-side navigation menu

Locate the **Webhook Integration** card.

If not connected yet, the card will display:

→ **Not Connected**

---

# **🔗 Step 2 — Enter Your Webhook URL**

Inside the Webhook Integration card:

→ Click **Connect Webhook**

Enter your webhook endpoint URL in the field provided.

### **Example**

`https://your-crm.com/api/popup-submissions`

Then:

→ Click **Save & Connect**

The app will mark the webhook as connected. The status badge changes to:

→ ✅ **Connected**

---

# **📋 Step 3 — Understand the Payload**

On every popup submission, the app sends a **POST** request to your webhook URL with the following JSON payload:

`{`  
  `"email": "user@example.com",`  
  `"phone": "+1234567890",`  
  `"EmailCollectionName": "My Popup Name",`  
  `"country": "United States",`  
  `"time": "14:30",`  
  `"date": "2025-01-15",`  
  `"isReturningCustomer": false`  
`}`

### **Field Descriptions**

| Field | Description |
| ----- | ----- |
| **email** | The email address submitted by the visitor |
| **phone** | The phone number submitted (if collected) |
| **EmailCollectionName** | The internal name of the popup that received the submission |
| **country** | The country detected from the visitor's location |
| **time** | The local time of the submission |
| **date** | The date of the submission |
| **isReturningCustomer** | `true` if the visitor has submitted before; `false` if new |

The request is sent with `Content-Type: application/json` and includes a 5-second timeout.

---

# **⚙️ Step 4 — How the Webhook Behaves**

* **Fires on every submission** — Regardless of popup type or content  
* **Non-blocking** — If your webhook endpoint is slow or down, the shopper's experience is not affected  
* **Automatic retries** — The app logs success and failure to the console; check your server logs if data doesn't arrive  
* **Real-time** — The payload is sent immediately after the submission is saved

---

# **✅ Step 5 — Save the Integration**

After entering your webhook URL:

→ Click **Save**

Your webhook integration is now active.

---

# **🧪 Step 6 — Test the Integration**

To verify your endpoint is receiving data:

→ Open your storefront in an **Incognito or Private** browser window  
→ Trigger a popup and submit a test email address

Example:

`testwebhook@example.com`

Then:

→ Check your webhook endpoint's logs or connected system  
→ Verify that a JSON payload arrived containing the test email, popup name, date, time, and location data

💡 If you don't have access to server logs, use a free webhook testing service (like webhook.site) as a temporary endpoint to inspect the payload structure.

---

# **⚠️ Common Troubleshooting**

## **Webhook Not Receiving Data**

If submissions happen but your endpoint receives nothing:

→ Verify the webhook URL is correct and uses **HTTPS**  
→ Verify the webhook is marked as **Connected** in the integration card  
→ Verify the popup is **published** and actively receiving submissions  
→ Check your server firewall or CDN rules — they may be blocking the request

## **Delayed or Missing Payloads**

If payloads are inconsistent:

→ The app uses a 5-second timeout — ensure your endpoint responds within that window  
→ The webhook is non-blocking; a slow endpoint will not stop the popup from working, but the request may time out  
→ Check server rate limits if you're receiving high submission volumes

## **Invalid JSON or Parsing Errors**

If your system can't read the payload:

→ The app sends `Content-Type: application/json` with a standard JSON body  
→ Ensure your endpoint expects JSON and not form-encoded data  
→ Some fields (like `phone`) may be empty strings if not collected — handle null/empty values gracefully

---

# **🎉 Final Result**

Once configured successfully:

✅ Every popup submission sends real-time data to your custom endpoint  
✅ Payload includes email, phone, popup name, location, timestamp, and returning-customer status  
✅ The shopper experience is never blocked by webhook delivery  
✅ You can connect Hoppy PopUps to virtually any system that accepts HTTP requests 🔗

---