# Popin Webhook Integration Guide

Popin’s webhook functionality allows you to receive real-time notifications about events happening in your Popin widget.

This guide explains how to set up webhooks and describes the event payloads you can expect to receive.

***

### 📌 Setting Up Webhooks

1. Log in to your **Popin Dashboard**.
2. Navigate to:\
   **Settings > Developers > Webhook**
3. Click **Setup**.
4. Enter your **Webhook URL** where Popin should send event notifications.
5. Use an **API key** for authentication, or `.` (dot) if an API key is not available.

If configured, the API key will be included in the request header as:

```
X-API-KEY: your_api_key
```

6. Save your settings.

✅ Once configured, Popin will `POST` event data to your specified URL whenever supported events occur.

***

### 📦 Supported Events and Payloads

#### 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",
  "user_id": "string",
  "email": "string",
  "country_code": "string",
  "phone_number": "string",
  "full_phone_number": "string",
  "timestamp": "string",
  "properties": {
    "customer_name": "string",
    "url": "string",
    "product": "string",
    "meta": "object"
  }
}
```

***

#### 3. Call Abandoned

**Event name:** `popin_call_abandoned`\
**Description:** Triggered when a call is abandoned before being answered.

```json
{
  "event": "popin_call_abandoned",
  "user_id": "string",
  "email": "string",
  "country_code": "string",
  "phone_number": "string",
  "full_phone_number": "string",
  "timestamp": "string",
  "properties": {
    "customer_name": "string",
    "url": "string",
    "product": "string",
    "meta": "object"
  }
}
```

***

#### 4. Call Remark Added

**Event name:** `popin_call_remark_added`\
**Description:** Triggered when a remark is added to a call.

```json
{
  "event": "popin_call_remark_added",
  "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",
    "remark": "string",
    "meta": "object"
  }
}
```

***

#### 5. Scheduled Call Created

**Event name:** `popin_scheduled_created`\
**Description:** Triggered when a call is scheduled.

```json
{
  "event": "popin_scheduled_created",
  "user_id": "string",
  "email": "string",
  "country_code": "string",
  "phone_number": "string",
  "full_phone_number": "string",
  "timestamp": "string",
  "properties": {
    "customer_name": "string",
    "scheduled_time": "string (format: h:i A)",
    "scheduled_date": "string (format: d-M-Y)",
    "scheduled_time_local": "string (format: h:i A)",
    "scheduled_date_local": "string (format: d-M-Y)",
    "url": "string",
    "agent_name": "string",
    "agent_email": "string",
    "product": "string",
    "meta": "object"
  }
}
```

***

#### 6. Missed Call Invited

**Event name:** `popin_missed_notification`\
**Description:** Triggered when a user is notified about a missed call.

```json
{
  "event": "popin_missed_notification",
  "user_id": "string",
  "email": "string",
  "country_code": "string",
  "phone_number": "string",
  "full_phone_number": "string",
  "timestamp": "string",
  "properties": {
    "customer_name": "string",
    "url": "string",
    "agent_name": "string",
    "agent_email": "string",
    "meta": "object"
  }
}
```

***

#### 7. Scheduled Call Notified

**Event name:** `popin_scheduled_notification`\
**Description:** Triggered when a user is notified about an upcoming scheduled call.

```json
{
  "event": "popin_scheduled_notification",
  "user_id": "string",
  "email": "string",
  "country_code": "string",
  "phone_number": "string",
  "full_phone_number": "string",
  "timestamp": "string",
  "properties": {
    "customer_name": "string",
    "scheduled_time": "string (format: h:i A)",
    "scheduled_date": "string (format: d-M-Y)",
    "scheduled_time_local": "string (format: h:i A)",
    "scheduled_date_local": "string (format: d-M-Y)",
    "url": "string",
    "agent_name": "string",
    "agent_email": "string",
    "meta": "object"
  }
}
```

***

#### 8. Scheduled Call Pre-Notified

**Event name:** `popin_prescheduled_notification`\
**Description:** Triggered when a user receives a pre-notification about an upcoming scheduled call.

```json
{
  "event": "popin_prescheduled_notification",
  "user_id": "string",
  "email": "string",
  "country_code": "string",
  "phone_number": "string",
  "full_phone_number": "string",
  "timestamp": "string",
  "properties": {
    "customer_name": "string",
    "scheduled_time": "string (format: h:i A)",
    "scheduled_date": "string (format: d-M-Y)",
    "scheduled_time_local": "string (format: h:i A)",
    "scheduled_date_local": "string (format: d-M-Y)",
    "url": "string",
    "agent_name": "string",
    "agent_email": "string",
    "meta": "object"
  }
}
```

***

#### 9. User Captured

**Event name:** `popin_user_captured`\
**Description:** Triggered when user details are captured.

```json
{
  "event": "popin_user_captured",
  "user_id": "string",
  "email": "string",
  "country_code": "string",
  "phone_number": "string",
  "full_phone_number": "string",
  "timestamp": "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 call is rated.

```json
{
  "event": "popin_call_rated",
  "user_id": "string",
  "email": "string",
  "country_code": "string",
  "phone_number": "string",
  "full_phone_number": "string",
  "timestamp": "string",
  "properties": {
    "customer_name": "string",
    "rating": "integer",
    "comments": "string",
    "url": "string",
    "agent_name": "string",
    "agent_email": "string",
    "meta": "object"
  }
}
```

***

#### 11. Call Guest Connected

**Event name:** `popin_call_guest_connected`\
**Description:** Triggered when a user or agent joins the ongoing call.

```json
{
  "event": "popin_call_guest_connected",
  "guest_type": "user/agent",
  "guest_id": "string", // Only if guest_type is "user"
  "guest_agent_name": "string", // Only if guest_type is "agent"
  "guest_agent_email": "string", // Only if guest_type is "agent"
  "timestamp": "string",
  "properties": {
    "url": "string",
    "agent_name": "integer",
    "agent_email": "string",
    "customer_name": "string",
    "customer_email": "string",
    "customer_country_code": "string",
"customer_phone_number": "string",
"full_phone_number": "string",
"meta": "object"
}
}
```

### 🗒 Notes

* `meta` and `extra` fields are reserved for additional contextual data.
* All payloads include identifiers (`user_id`, `email`, `phone_number`) for mapping with your system.
* Timestamps may be formatted differently depending on event type (e.g., `d-M-Y`, `h:i A`).

***

### ✅ Best Practices

* **Verify the source**: Validate incoming webhooks are from Popin (e.g., check IP or API key).
* **Handle duplicates**: Use **idempotency** to handle repeated events safely.
* **Respond quickly**: Your endpoint should respond within a few seconds to avoid timeouts.
* **Error handling**: Implement **retry logic** for failed webhook deliveries.

***

### 🔧 Troubleshooting

If you're not receiving webhook notifications:

* ✅ Verify your webhook URL in the **Popin dashboard**.
* 🪵 Check your **server logs** for incoming requests.
* 🌍 Ensure your endpoint is **publicly accessible**.
* 🔐 Review **firewall/security settings** that may block requests.
