Popin Webhook Integration Guide

Popin's webhook functionality allows your application to receive real-time notifications about specific events occurring within the Popin widget. This guide walks you through how to configure webhooks, details the supported event types, and provides example payloads.

---

📌 Overview

Popin webhooks are HTTP POST requests sent to your server when certain actions happen in your widget. These allow for automation and tracking of user interactions in real time.

---

🔧 Setting Up Webhooks

To start receiving webhook notifications, follow these steps:

1. Log in to your Popin Dashboard.

2. Navigate to: Settings → Developers → Webhook

3. Click Setup.

4. Enter your Webhook URL – the endpoint that will receive event data.

5. (Optional) Add an API Key for securing the requests.

🔐 Authentication

If an API key is set, it will be included in the request headers as:

X-API-KEY: your_api_key

1. Click Save to finish setup.

Once configured, Popin will send HTTP POST requests to your webhook URL for each supported event.

---

📦 Supported Events & Payloads

Each webhook event has a specific event name and JSON payload. Below is a list of all supported events.

1. ✅ Call Successful

Event Name: popin_call_successful Description: Triggered when a call is successfully completed.

{
  "event": "popin_call_successful",
  "user_id": "string",
  "email": "string",
  "country_code": "string",
  "phone_number": "string",
  "full_phone_number": "string",
  "timestamp": "string",
  "properties": {
    "customer_name": "string",
    "call_duration": "string",
    "url": "string",
    "agent_name": "string",
    "agent_email": "string",
    "product": "string",
    "meta": "object"
  }
}

---

2. ❌ Call Missed

Event Name: popin_call_missed Description: Triggered when a call is missed.

{
  "event": "popin_call_missed",
  ...
}

(Same structure as above, with relevant fields)

---

3. 📞 Call Abandoned

Event Name: popin_call_abandoned Description: Triggered when a call is abandoned before being answered.

---

4. 📝 Call Remark Added

Event Name: popin_call_remark_added Description: Triggered when a remark is added to a call.

---

5. 🗓️ Scheduled Call Created

Event Name: popin_scheduled_created Description: Triggered when a call is scheduled.

{
  "event": "popin_scheduled_created",
  ...
}

Includes scheduled time, date, agent info, and product details.

---

6. 🔔 Missed Call Invited

Event Name: popin_missed_notification Description: Triggered when a user is notified about a missed call.

---

7. 📆 Scheduled Call Notified

Event Name: popin_scheduled_notification Description: Triggered when a user is notified about an upcoming scheduled call.

---

8. ⏰ Scheduled Call Pre-Notified

Event Name: popin_prescheduled_notification Description: Triggered when a user receives a pre-notification of a scheduled call.

---

9. 👤 User Captured

Event Name: popin_user_captured Description: Triggered when a user's contact details are captured.

{
  "event": "popin_user_captured",
  "user_id": "string",
  ...
  "properties": {
    "customer_name": "string",
    "customer_email": "string",
    "customer_country_code": "string",
    "customer_phone_number": "string",
    "extra": "object",
    "meta": "object"
  }
}

---

10. ⭐ Call Rated

Event Name: popin_call_rated Description: Triggered when a user rates a completed call.

{
  "event": "popin_call_rated",
  ...
  "properties": {
    "rating": "integer",
    "comments": "string",
    ...
  }
}

---

11. 🔗 Call Guest Connected

Event Name: popin_call_guest_connected Description: Triggered when a user or agent joins an ongoing call.

{
  "event": "popin_call_guest_connected",
  "guest_type": "user/agent",
  ...
}

---

📝 Notes on Payload Structure

• meta and extra: Reserved for additional contextual or custom data.

• User identification: All events include:

  • user_id

  • email

  • phone_number

• Timestamps: Format varies depending on the event.

  • Example: d-M-Y, h:i A

---

✅ Best Practices

To ensure robust webhook handling:

• Verify authenticity: Validate source IP or use the X-API-KEY header.

• Idempotency: Safely handle repeated events to avoid duplicate processing.

• Respond quickly: Ensure your server replies within a few seconds to avoid timeouts.

• Retries: Implement retry logic for failed deliveries.

---

🛠️ Troubleshooting

If you're not receiving webhooks:

• Double-check the webhook URL in your Popin Dashboard.

• Inspect server logs for incoming POST requests.

• Ensure your endpoint is publicly accessible.

• Review security settings (e.g., firewalls, IP restrictions).

• Confirm your server returns a 2xx HTTP status for successful receipt.