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:

Log in to your Popin Dashboard.
Navigate to: Settings → Developers → Webhook
Click Setup.
Enter your Webhook URL – the endpoint that will receive event data.
(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

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.

PreviousSales Tracking on Shopify NextPassing Campaign Data via Popin & Webhook (Meta)

Last updated 2 months ago