EmiliaVision POS Webhook Integration Documentation¶

Welcome! This documentation will guide you through integrating your POS system with EmiliaVision's analytics platform via webhooks.

📚 Documentation Structure¶

1. 🚀 Quick Start Guide ¶

Start here if you want to: - Send your first webhook in 15 minutes - Get a working integration quickly - See code examples in Python and Node.js - Follow a step-by-step implementation path

Time to first webhook: 15 minutes

Comprehensive guide covering: - Why this integration matters for your business - Two integration strategies (Real-time vs End-of-session) - What data to send and why it's valuable - Complete implementation examples - Production checklist

Best for: Understanding the full picture and value proposition

3. 🔧 API Reference ¶

Technical specification including: - Complete field definitions - All event types and payloads - Response codes and error handling - Rate limits and constraints - Testing procedures

Best for: Technical implementation details

4. 🔍 Troubleshooting & Best Practices ¶

Problem-solving guide with: - Common issues and solutions - Best practices for production - Monitoring and alerting strategies - Diagnostic tools and scripts - Performance optimization tips

Best for: Debugging issues and optimizing your integration

🎯 Implementation Path¶

Week 1: Basic Integration¶

Read the Quick Start Guide
Get your webhook token from [email protected]
Send test webhooks with minimal data (table number + times)
Verify data appears in development dashboard

Week 2: Enhanced Data¶

Review the Integration Guide
Add financial data (totals, tips, taxes)
Include item-level details with timestamps
Add employee/server information

Week 3: Production Ready¶

Study the API Reference
Implement proper error handling and retries
Set up monitoring and logging
Switch from development to production environment

Ongoing: Optimization¶

Use Troubleshooting Guide for issues
Implement real-time updates as events happen
Optimize performance with batching and queuing
Monitor success rates and response times

🔑 Critical Information¶

Your Webhook URL¶

https://api.emiliavision.com/webhooks/v1/pos/{YOUR_TOKEN}

Environments¶

Testing: Add ?env=dev to URL
Production: Use base URL (default)

Most Important Fields¶

table_number - CRITICAL! Links to video analytics
session_start - When table was opened
session_end - When check was closed
items[].timestamp - When each item was ordered (GOLD!)
employee_id - Who performed each action

Minimum Viable Webhook¶

{
  "event": "session_complete",
  "order_id": "ORD-123",
  "table_number": "Mesa 8",     // CRITICAL!
  "session_start": "2025-11-24T18:30:00-03:00",
  "session_end": "2025-11-24T20:15:00-03:00",
  "timestamp": "2025-11-24T20:15:00-03:00"
}

💡 Why This Integration Matters¶

By combining your POS data with our video analytics, you'll get:

Real-time table turnover metrics - Know exactly how long tables are occupied
Staff performance insights - Track service speed by server
Revenue optimization - Identify bottlenecks and peak times
Kitchen timing analysis - Understand preparation and service flow
Customer experience metrics - Correlate wait times with satisfaction

🏆 Success Metrics¶

What Good Looks Like¶

Data Quality¶

✅ 100% of sessions include table_number
✅ 95%+ include item-level timestamps
✅ 90%+ include employee information
✅ All timestamps include timezone

Integration Performance¶

✅ < 500ms average response time
✅ > 99% webhook success rate
✅ Real-time updates (within 5 minutes)
✅ Automatic retry on failures

Business Value¶

✅ Complete visibility of table operations
✅ Accurate correlation with video data
✅ Actionable insights within 24 hours
✅ Measurable improvement in table turnover

🆘 Support¶

Getting Your Token¶

Email: [email protected] - Include: Restaurant name, location, POS system - Response time: < 24 hours

Technical Support¶

Email: [email protected] - Include: Token (first 8 chars), error messages, sample payload - Response time: < 4 hours

Integration Review¶

Schedule a call: https://cal.com/cajiao+arpagon/dynamic?user=cajiao%2Barpagon&duration=30 - Review your implementation - Optimize data quality - Plan enhancements

📊 Example: Complete Integration¶

Here's what a fully-integrated session looks like with all the valuable data:

{
  "event": "session_complete",
  "timestamp": "2025-11-24T20:15:00-03:00",
  "order_id": "ORD-2025-0124",
  "table_number": "Mesa 8",
  "session_start": "2025-11-24T18:30:00-03:00",
  "session_end": "2025-11-24T20:15:00-03:00",
  "duration_minutes": 105,

  "opened_by": {
    "id": 72,
    "name": "João Silva"
  },

  "closed_by": {
    "id": 96,
    "name": "Maria Santos"
  },

  "items": [
    {
      "timestamp": "2025-11-24T18:35:00-03:00",  // When ordered!
      "employee_id": 72,                         // Who took order!
      "name": "Focaccia",
      "quantity": 1,
      "price": 19.00
    },
    {
      "timestamp": "2025-11-24T18:35:00-03:00",
      "employee_id": 72,
      "name": "Agua com Gas",
      "quantity": 2,
      "price": 11.00
    },
    {
      "timestamp": "2025-11-24T18:45:00-03:00",  // Second round
      "employee_id": 72,
      "name": "Carbonara Classica",
      "quantity": 1,
      "price": 85.00
    },
    {
      "timestamp": "2025-11-24T19:50:00-03:00",  // Dessert time
      "employee_id": 96,                         // Different server
      "name": "Tiramisu",
      "quantity": 2,
      "price": 36.00
    }
  ],

  "totals": {
    "subtotal": 187.00,
    "tip": 24.31,
    "tax": 18.70,
    "total": 230.01
  },

  "payment": {
    "method": "VISA_CREDIT",
    "fiscal_receipt": "NFe35251133111140001168650020000762241540579084"
  }
}

✅ Ready to Start?¶

Get your token: Email [email protected]
Read the Quick Start: quickstart.md
Send a test webhook: Takes just 30 seconds
See your data: Check the development dashboard
Iterate and improve: Add more data gradually

Remember: Start simple, iterate quickly. Even basic data provides valuable insights!

Questions? Start with the Quick Start Guide or email [email protected]

Version: 2.0 | Last Updated: November 2025