> For the complete documentation index, see [llms.txt](https://popin.gitbook.io/popin-developer-hub/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://popin.gitbook.io/popin-developer-hub/popin-webhook-integration-guide.md).

# 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 > Integrations > 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.
6. If configured, the API key will be included in the request header as:

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

7. 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",
  "guest_agent_name": "string",
  "guest_agent_email": "string",
  "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"
}
```

#### 12. User OTP Requested

**Event name:** `popin_user_otp`\
**Description:** Triggered when a user requests an OTP to verify the contact detail provided.

```json
{
  "event": "popin_user_otp",
  "user_id": "string",
  "country_code": "string",
  "phone_number": "string",
  "full_phone_number": "string",
  "properties": {
    "otp": "string",
    "customer_name": "string",
    "customer_country_code": "string",
    "customer_phone_number": "string"
  },
  "meta": "object",
  "timestamp": "string"
}
```

#### 13. Call Not Ringing

**Event name:** `popin_call_not_ringing`\
**Description:** Triggered when an incoming call fails to ring on the agent's device.

```json
{
  "event": "popin_call_not_ringing",
  "user_id": "string",
  "email": "string",
  "country_code": "string",
  "phone_number": "string",
  "full_phone_number": "string",
  "properties": {
    "agent_name": "string",
    "agent_email": "string",
    "customer_name": "string",
    "customer_email": "string",
    "customer_country_code": "string",
    "customer_phone_number": "string"
  },
  "meta": "object",
  "timestamp": "string"
}
```

### 🗒 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.