> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://lobbyfix.crisp.help/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Integrations

# Webhook Integration Guide - LobbyFix

###### Overview
[What are Webhooks?](#what-are-webhooks)
[Prerequisites](#prerequisites)

###### Implementation
[Step 1: Configure Your Webhook](#step-1-configure-your-webhook)
[Step 2: What Data Do You Receive?](#step-2-what-data-do-you-receive)
[Step 3: Monitor Your Webhooks](#step-3-monitor-your-webhooks)

###### Administration
[Enable / Disable Webhooks](#enable-disable-webhooks)
[Event Types](#event-types)

###### Support
[Common Errors](#why-do-webhooks-fail)
[Popular Integrations](#popular-integrations)
[Code Examples](#code-examples)
[Frequently Asked Questions](#frequently-asked-questions)

## What are Webhooks?

Webhooks allow you to receive real-time automatic notifications when visitors enter or leave your location. Think of them as a virtual assistant that instantly notifies you whenever something important happens at your reception.

**Common use cases:**
* 🚪 Automatically open doors when a visitor is approved
* 💬 Send Slack notifications when a VIP visitor arrives
* 📊 Log visits in your internal reporting system
* 🔔 Send custom alerts to your team
* 🎫 Automatically generate tickets or access codes

---

## Prerequisites

Before configuring your webhooks, make sure you have:

1. ✅ **An active LobbyFix account** with administrator permissions
2. ✅ **The Integrations module enabled** for your location (contact support if you don’t see it)
3. ✅ **A public HTTPS URL** where your system can receive notifications
* This can be your own server
* Or a service like Zapier, Make.com, or n8n

> 💡 **Don’t have a server?** You can use tools like [webhook.site](https://webhook.site) for testing, or automation platforms like Zapier that provide ready-to-use webhook URLs.

---

## Step 1: Configure Your Webhook

### From the Web Platform

1. **Log in** to your LobbyFix account
2. Go to **Account** (top-right corner) and select the **Integrations** tab
3. Click the blue **"+ Add"** button
4. Complete the form:

   **Name**  
   A descriptive name to identify this integration  
   Example: `Slack Notifications`, `Access Control System`, `Internal CRM`

   **Webhook URL**  
   The HTTPS address where you want to receive notifications  
   Example: `https://your-server.com/webhooks/lobbyfix`

   > ⚠️ **Important:** The URL must start with `https://` (not `http://`)

   **Events to send**  
   Select which events you want to receive:
* ☑️ **Visitor checked in** - Triggered when a visitor physically enters
* ☑️ **Visitor checked out** - Triggered when a visitor leaves the location

5. Click **"Create Integration"**

![Create Integration](https://storage.crisp.chat/users/helpdesk/website/-/1/a/1/5/1a157f5daa9e7500/screenshot-from-2026-01-15-11-_5kpmvh.png)

### Test Your Webhook

After creating the webhook:

1. Find your webhook in the integrations list
2. Click **"Test Webhook"**
3. If everything is working, you’ll see a green message: **"✓ Success (XXXms)"**
4. If there’s an error, verify that your URL is correct and publicly accessible

![Test Webhook](https://i.imgur.com/example2.png)

---

## Step 2: What Data Do You Receive?

When an event occurs, LobbyFix sends a JSON payload to your URL with full visitor details.

### Check-in Notification Example

```json
{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "visitor.checked_in",
  "timestamp": "2025-01-14T18:30:45.000Z",
  "data": {
    "checkin": {
      "id": 11761,
      "status": "INSIDE_LOCATION",
      "motive": "MEETING",
      "host": "Juan Pérez",
      "photo": "https://regiztra-s3.amazonaws.com/...",
      "created_at": "2025-01-14T18:30:45.000Z",
      "checked_in_at": "2025-01-14T18:30:45.000Z",
      "approval_method": "auto"
    },
    "visitor": {
      "id": 456,
      "name": "María García",
      "company_name": "Acme Corp",
      "phone": "+52 55 1234 5678"
    },
    "location": {
      "id": 42
    }
  }
}
```

| Field | Description | Example |
| ---- |
| **event_type** | Event type | `visitor.checked_in` or `visitor.checked_out` |
| **timestamp** | Event date and time | `2025-01-14T18:30:45.000Z` |
| **visitor.name** | Visitor name | `María García` |
| **visitor.company_name** | Visitor company | `Acme Corp` |
| **visitor.phone** | Visitor phone | `+52 55 1234 5678` |
| **checkin.host** | Host receiving the visitor | `Juan Pérez` |
| **checkin.motive** | Visit reason | `MEETING`, `DELIVERY`, etc. |
| **checkin.photo** | Visitor photo URL | Temporary signed link |
| **checkin.checked_in_at** | Check-in time | `2025-01-14T18:30:45.000Z` |
| **checkin.checked_out_at** | Check-out time (checkout only) | `2025-01-14T19:15:30.000Z` |

## Step 3: Monitor Your Webhooks

### View Delivery History

1. Go to **Account > Integrations**
2. Find your webhook and click **“View Logs”**
3. You will see a list of all events that have been sent:

* **Green status (200 OK):** Delivered successfully ✅
* **Red status:** Delivery failed ❌
* **Latency:** How long your server took to respond
* **Date:** When the notification was sent

![Webhook Logs](https://storage.crisp.chat/users/helpdesk/website/-/1/a/1/5/1a157f5daa9e7500/image_1jkon54.png)

4. Click **“View”** to see full details:
* **REQUEST:** What LobbyFix sent to your server
* **RESPONSE:** What your server returned

### Status Indicators

In the integrations list, you will see:
* **ACTIVE** (green): The webhook is working
* **DISABLED** (red): The webhook is paused
* **Last used:** How long ago it was triggered

---

## Enable / Disable Webhooks

You can temporarily pause a webhook without deleting it:

1. Go to **Account > Integrations**
2. Use the **toggle switch** next to the webhook name
3. Green = Active | Gray = Disabled

This is useful when:
* You are performing server maintenance
* You want to test changes without receiving events
* You need to temporarily pause an integration

---

## Edit or Delete Webhooks

### Edit a Webhook

1. Go to **Account > Integrations**
2. Click the **pencil icon** ✏️ next to the webhook
3. Update the fields you need:
* Change the name
* Update the URL
* Add or remove events
4. Click **“Save Changes”**

### Delete a Webhook

1. Go to **Account > Integrations**
2. Click the **trash icon** 🗑️ next to the webhook
3. Confirm deletion

> ⚠️ **Note:** This action cannot be undone. If you delete a webhook by mistake, you will need to create it again.

---

## Event Types

### 🟢 Visitor Checked In (`visitor.checked_in`)

**Triggered when:**
* A visitor completes reception check-in and physically enters
* The check-in status changes to `INSIDE_LOCATION`

**Not triggered when:**
* A visitor is waiting
* A visitor is approved but has not entered yet
* A visitor is rejected

**Use cases:**
* Automatically open turnstiles or doors
* Notify the host that their visitor has arrived
* Record the exact entry time

### 🔴 Visitor Checked Out (`visitor.checked_out`)

**Triggered when:**
* A visitor checks out in the system
* The system detects an automatic checkout (if enabled)

**Use cases:**
* Revoke temporary access permissions
* Calculate visit duration
* Send satisfaction surveys upon exit

---

## Advanced Configuration: Priorities

When creating or editing a webhook, you can configure delivery priority:

### 🟦 NORMAL (Recommended)

* **Timeout:** 10 seconds
* **Retries:** Up to 6 attempts if delivery fails
* **Delivery:** Queued (does not block the check-in flow)

**Use NORMAL for:**
* Slack, Microsoft Teams, and similar notifications
* CRM or reporting integrations
* Any use case where a few seconds of delay is acceptable

### ⚡ HIGH (High Priority)

* **Timeout:** 5 seconds
* **Retries:** Up to 3 fast attempts
* **Delivery:** Immediate (may impact check-in time)

**Use HIGH for:**
* Physical access control systems (doors, turnstiles)
* Real-time validations that must complete before granting access
* Critical integrations that require an immediate response

> ⚠️ **Warning:** If your HIGH-priority endpoint takes longer than 5 seconds to respond, the check-in process may be delayed. Use this option only if absolutely necessary.

---

## Why Do Webhooks Fail?

### Issue 1: 403 / 404 / 500 Errors

**Cause:** Your server rejected the request or is unavailable

**Solution:**
1. Verify the URL is correct (no spaces or extra characters)
2. Test the URL manually
3. Review your server logs to identify the error
4. Ensure your application is running

### Issue 2: Timeout (No Response)

**Cause:** Your server is taking too long to respond

**Solution:**
1. Your server must respond in under 10 seconds (5 seconds if HIGH)
2. Avoid heavy operations before returning `200 OK`
3. Process the payload asynchronously (after responding)

### Issue 3: Invalid SSL Certificate

**Cause:** Your URL uses HTTPS but the certificate is not valid

**Solution:**
1. Use a valid SSL certificate (Let’s Encrypt is free)
2. Do not use self-signed certificates
3. Verify your domain is correctly configured for HTTPS

### Issue 4: Not Receiving Notifications

**Possible causes:**

✓ **Webhook is disabled**  
→ Ensure the toggle is green (ACTIVE)

✓ **Events not selected**  
→ Edit the webhook and confirm at least one event is selected

✓ **Integrations module not enabled**  
→ Contact support to enable this module for your account

✓ **Incorrect URL**  
→ The URL must be accessible from the public internet (not localhost)

✓ **Firewall or IP blocking**  
→ Ensure your server allows incoming connections from AWS

---

## Webhook Automatically Disabled

If your webhook fails **50 consecutive times**, LobbyFix will automatically disable it to protect both systems.

### How will I know?

1. You will receive an **email notification** explaining the webhook was disabled
2. In the platform, the status will show **DISABLED** in red
3. The reason will be displayed in the logs

### What should I do?

1. **Identify the issue**
* Open **View Logs** and review recent errors
* Look for patterns (timeouts, 500 errors, invalid URL)

2. **Fix the issue**
* Resolve the problem on your server
* Update the webhook if the URL changed

3. **Test manually**
* Use the **“Test Webhook”** button to confirm it works

4. **Re-enable the webhook**
* Toggle from **DISABLED** to **ACTIVE**
* Monitor the first deliveries to confirm stability

---

## Popular Integrations

### Slack

Receive notifications in your Slack channel when visitors arrive.

**Steps:**
1. In Slack, create an [Incoming Webhook](https://api.slack.com/messaging/webhooks)
2. Copy the Slack URL (e.g. `https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXX`)
3. Use an intermediary service such as Zapier or Make.com to transform the LobbyFix payload into Slack’s format

### Zapier

Connect LobbyFix with thousands of applications without writing code.

**Steps:**
1. Create a new Zap in [Zapier](https://zapier.com)
2. Select **Webhooks by Zapier** as the trigger
3. Copy the webhook URL provided by Zapier
4. Paste it into LobbyFix as your Webhook URL
5. Configure the actions you want to perform (send email, create ticket, etc.)

### Make.com (formerly Integromat)

Similar to Zapier, allows you to connect LobbyFix with other applications.

**Steps:**
1. Create a new Scenario in [Make.com](https://make.com)
2. Add **Webhooks > Custom webhook**
3. Copy the webhook URL
4. Paste it into LobbyFix
5. Configure modules to process the data

### n8n (Open Source)

If you prefer to host your own automation solution.

**Steps:**
1. Install [n8n](https://n8n.io) on your server
2. Create a new workflow with a **Webhook** node
3. Configure the node to receive POST requests
4. Copy the webhook URL
5. Use it in LobbyFix

---

## Code Examples

### Receive Webhooks with Node.js

```javascript
const express = require('express');
const app = express();

// Middleware to parse JSON
app.use(express.json());

// Endpoint to receive LobbyFix webhooks
app.post('/webhooks/lobbyfix', (req, res) => {
  const { event_type, data } = req.body;
  const { visitor, checkin } = data;

  console.log(`Event: ${event_type}`);
  console.log(`Visitor: ${visitor.name}`);
  console.log(`Company: ${visitor.company_name}`);
  console.log(`Host: ${checkin.host}`);

  // Respond immediately
  res.status(200).json({ received: true });

  // Process asynchronously
  processWebhook(event_type, data);
});

function processWebhook(eventType, data) {
  if (eventType === 'visitor.checked_in') {
    console.log('Visitor checked in');
  } else if (eventType === 'visitor.checked_out') {
    console.log('Visitor checked out');
  }
}

app.listen(3000, () => {
  console.log('Server listening on port 3000');
});
```

### Receive Webhooks with PHP

```php
<?php
// Get JSON payload
$payload = file_get_contents('php://input');
$data = json_decode($payload, true);

// Validate the request
if (!$data || !isset($data['event_type'])) {
    http_response_code(400);
    echo json_encode(['error' => 'Invalid payload']);
    exit;
}

// Extract data
$eventType = $data['event_type'];
$visitor = $data['data']['visitor'];
$checkin = $data['data']['checkin'];

// Debug logs
error_log("Webhook received: $eventType");
error_log("Visitor: {$visitor['name']}");

// Respond quickly with 200 OK
http_response_code(200);
echo json_encode(['received' => true]);

// Process after responding
if ($eventType === 'visitor.checked_in') {
    // Visitor checked in
    processCheckin($visitor, $checkin);
} elseif ($eventType === 'visitor.checked_out') {
    // Visitor checked out
    processCheckout($visitor, $checkin);
}

function processCheckin($visitor, $checkin) {
    // Your logic here
    // Example: insert into database
    $pdo = new PDO('mysql:host=localhost;dbname=mydb', 'user', 'pass');
    $stmt = $pdo->prepare("INSERT INTO visits (name, company, checkin_time) VALUES (?, ?, ?)");
    $stmt->execute([
        $visitor['name'],
        $visitor['company_name'],
        $checkin['checked_in_at']
    ]);
}

function processCheckout($visitor, $checkin) {
    // Your logic here
}
?>
```
### Receive Webhooks with Python (Flask)

```python
from flask import Flask, request, jsonify
from datetime import datetime

app = Flask(__name__)

@app.route('/webhooks/lobbyfix', methods=['POST'])
def webhook():
    # Get payload
    payload = request.get_json()

    if not payload or 'event_type' not in payload:
        return jsonify({'error': 'Invalid payload'}), 400

    event_type = payload['event_type']
    visitor = payload['data']['visitor']
    checkin = payload['data']['checkin']

    # Logs
    print(f"Event: {event_type}")
    print(f"Visitor: {visitor['name']}")
    print(f"Company: {visitor.get('company_name')}")
    print(f"Host: {checkin.get('host')}")

    # Respond quickly with 200 OK
    response = jsonify({'received': True})

    # Process after responding (example)
    if event_type == 'visitor.checked_in':
        process_checkin(visitor, checkin)
    elif event_type == 'visitor.checked_out':
        process_checkout(visitor, checkin)

    return response, 200

def process_checkin(visitor, checkin):
    # Your logic here
    print(f"Processing check-in for {visitor['name']}")
    # Example: write to database, send email, etc.

def process_checkout(visitor, checkin):
    # Your logic here
    print(f"Processing check-out for {visitor['name']}")

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=3000)
```

---

## Best Practices

### ✅ Recommendations

1. **Respond quickly (< 3 seconds)**
* Return `200 OK` immediately
* Process the payload asynchronously (after responding)

2. **Validate the payload**
* Verify required fields exist in the JSON
* Handle cases where optional fields are missing

3. **Log everything**
* Store each webhook you receive
* This will help with debugging issues

4. **Avoid duplicates**
* Use `event_id` to detect repeated events
* Store processed IDs in a database

5. **Handle errors**
* If your internal logic fails, still return 200 OK
* Do not let internal errors block webhook reception

6. **Monitor actively**
* Review LobbyFix logs periodically
* Configure alerts if failures increase

7. **Use HTTPS**
* Never use HTTP (it will not work)
* Ensure you have a valid SSL certificate

### ❌ Common Mistakes

1. **Processing before responding**
* ❌ Process data → Respond 200
* ✅ Respond 200 → Process data

2. **Using HTTP instead of HTTPS**
* ❌ `http://my-server.com/webhook`
* ✅ `https://my-server.com/webhook`

3. **Doing slow operations before responding**
* ❌ Sending emails, calling external APIs, processing images
* ✅ Enqueue and process later

4. **Not validating the payload**
* ❌ Assuming all fields always exist
* ✅ Validate required fields and use safe defaults

5. **Ignoring retries**
* ❌ Not detecting duplicate events
* ✅ Use `event_id` to avoid double-processing

---

## Frequently Asked Questions

### Can I have multiple webhooks?

Yes. You can create as many webhooks as you need. For example:
* One webhook for Slack
* Another webhook for your access control system
* Another webhook for your CRM

Each webhook can subscribe to different events.

### Do webhooks cost extra?

Please check with your sales representative to confirm what is included in your plan.

### Can I test without my own server?

Yes. Use [webhook.site](https://webhook.site) to view incoming payloads. You can also use Zapier or Make.com which provide ready-to-use webhook URLs.

### What happens if my server is down?

LobbyFix will retry delivery up to 6 times with increasing delays. If it still fails, the event will be marked as failed.

### Can I recover missed events?

Events are not resent automatically, but you can:
1. View the payload in logs (**View Logs > View > REQUEST**)
2. Copy it and send it manually to your server
3. Or retrieve it via API using the check-in ID

### Can I filter events?

You can currently choose between:
* Check-ins only (`visitor.checked_in`)
* Check-outs only (`visitor.checked_out`)
* Both

There are no more specific filters (for example, VIP-only). You would need to filter in your own system.

### Does the visitor photo expire?

Yes. The photo URL is temporary (AWS S3 signed URL). If you need the photo:
1. Download it immediately when you receive the webhook
2. Store it in your own storage
3. Do not store only the URL

### Can I use localhost for testing?

No. The URL must be publicly accessible. For local development:
* Use [ngrok](https://ngrok.com) to expose localhost
* Or use webhook.site to inspect payloads
* Or deploy to a staging server

---

## Support

Need help?

📧 **Email:** support@lobbyfix.com  
💬 **Chat:** Available in the platform (bottom-right corner)  
📞 **Phone:** Check your portal for the support phone number

**When contacting support, include:**
* Webhook name or ID
* Screenshot of the logs (if applicable)
* Description of the issue
* Webhook URL (if it is safe to share)

---

## Additional Resources

* 🌐 [webhook.site](https://webhook.site) - Webhook testing tool
* 🔗 [Zapier](https://zapier.com) - No-code automation
* 🔗 [Make.com](https://make.com) - Zapier alternative
* 🔧 [ngrok](https://ngrok.com) - Expose localhost for testing
* 📘 [Postman](https://postman.com) - API testing tool

---

**Last updated:** January 2026  
**Version:** 1.0

---

*This documentation is intended for LobbyFix users. For API-level technical documentation, contact the development team.*
```