# 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
```

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

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

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

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

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

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

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