{"id":21532156,"url":"https://github.com/thesethrose/omi-webhook-server","last_synced_at":"2025-08-17T12:32:55.017Z","repository":{"id":263491249,"uuid":"890571596","full_name":"TheSethRose/Omi-Webhook-Server","owner":"TheSethRose","description":"A Python server that receives and processes webhook notifications from the Omi app. This server handles real-time memory creation, audio streaming, and transcription events for Omi wearable devices.","archived":false,"fork":false,"pushed_at":"2024-11-18T22:29:21.000Z","size":37,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-24T06:29:54.316Z","etag":null,"topics":["flask-server","omi"],"latest_commit_sha":null,"homepage":"https://www.omi.me","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TheSethRose.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-18T20:01:40.000Z","updated_at":"2024-11-18T22:29:24.000Z","dependencies_parsed_at":"2024-11-19T06:15:26.341Z","dependency_job_id":null,"html_url":"https://github.com/TheSethRose/Omi-Webhook-Server","commit_stats":null,"previous_names":["thesethrose/omi-webhook-server"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheSethRose%2FOmi-Webhook-Server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheSethRose%2FOmi-Webhook-Server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheSethRose%2FOmi-Webhook-Server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheSethRose%2FOmi-Webhook-Server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheSethRose","download_url":"https://codeload.github.com/TheSethRose/Omi-Webhook-Server/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244096216,"owners_count":20397365,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flask-server","omi"],"created_at":"2024-11-24T02:18:59.483Z","updated_at":"2025-03-17T19:28:59.107Z","avatar_url":"https://github.com/TheSethRose.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Omi Webhook Server\n\nA Python server that receives and processes webhook notifications from the [Omi](https://github.com/BasedHardware/omi) app. This server handles real-time memory creation, audio streaming, and transcription events for Omi wearable devices.\n\n## Important Note\n\nThis webhook server provides the foundation for receiving events from the Omi app (memory creation, audio streaming, transcripts), but it doesn't include default actions or behaviors for these events. You'll need to implement your own logic for handling these events.\n\n## Installation\n\n### Option 1: Docker (Recommended)\n\n1. Clone this repository\n2. Copy the example environment file:\n\n   ```bash\n   cp env.example .env\n   ```\n\n3. Generate and set your webhook secret:\n\n   ```bash\n   python -c \"import secrets; print(secrets.token_hex(32))\"\n   # Add the generated secret to .env\n   ```\n\n4. Start the server:\n\n   ```bash\n   docker compose up -d\n   ```\n\nThe server will be available at `http://localhost:32768` with:\n\n- Automatic restarts on failure\n- Health monitoring\n- Log management\n- Dependency handling\n\nMonitor your server:\n\n```bash\ndocker compose ps    # View status\ndocker compose logs  # View logs\n```\n\n### Option 2: Manual Installation\n\n1. Install dependencies:\n\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n2. Set up environment:\n\n   ```bash\n   cp env.example .env\n   # Edit .env with your settings\n   ```\n\n3. Start server:\n\n   ```bash\n   python server.py\n   ```\n\n## Configuration\n\n### Environment Variables\n\nKey settings in your `.env` file:\n\n```bash\nPORT=32768                # Server port\nHOST=0.0.0.0             # Server host\nWEBHOOK_SECRET=your_key   # Authentication secret\nLOG_LEVEL=INFO           # Logging verbosity\nLOG_EVENTS=true          # Detailed event logging\n```\n\n### Logging Configuration\n\nTwo logging controls:\n\n1. `LOG_LEVEL`: General verbosity (INFO, WARNING, ERROR, DEBUG, CRITICAL)\n2. `LOG_EVENTS`: Event detail logging (true/false)\n\nExample logs:\n\n```bash\n# With LOG_EVENTS=false\n2024-03-20 14:23:06 [INFO] memory_created | uid:test-user-1 | status:200\n\n# With LOG_EVENTS=true\n2024-03-20 14:23:06 [INFO] memory_created | uid:test-user-1 | status:200 | data:{...} | response:{...}\n```\n\n## Usage\n\n### Webhook URL Format\n\n```bash\nhttp://your-server:32768/webhook?key=YOUR_SECRET\n```\n\n### Supported Events\n\n1. Memory Events\n   - `memory_created`: New memory creation\n   - `memory_processing_started`: Processing initiation\n   - `processing_memory_status_changed`: Status updates\n   - `memory_backward_synced`: Sync completion\n\n2. Audio Events\n   - `audio_bytes`: Real-time PCM audio streaming\n\n3. Transcript Events\n   - `transcript_segment`: Real-time speech-to-text\n\n4. System Events\n   - `ping`: Health check endpoint\n\n### Event Payload Examples\n\nMemory Event:\n\n```json\n{\n    \"type\": \"memory_created\",\n    \"memory\": {\n        \"id\": \"memory_id\",\n        \"created_at\": \"ISO8601_timestamp\",\n        \"text\": \"memory_content\"\n    }\n}\n```\n\nAudio Event:\n\n```json\n{\n    \"type\": \"audio_bytes\",\n    \"audio\": \"hex_encoded_pcm_audio\"\n}\n```\n\nTranscript Event:\n\n```json\n{\n    \"type\": \"transcript_segment\",\n    \"segment\": {\n        \"text\": \"transcribed_text\",\n        \"start_time\": 0.0,\n        \"end_time\": 2.5\n    }\n}\n```\n\n## Development\n\n### Project Structure\n\n```bash\nomi-webhook/\n├── events/                 # Event handlers\n├── tests/                 # Test suites\n├── server.py             # Main server\n├── test.py              # Test runner\n└── .env                # Configuration\n```\n\n### Testing\n\nRun tests:\n\n```bash\npython test.py\n```\n\n### Local Development with Omi App\n\n1. Start server:\n\n   ```bash\n   python server.py\n   ```\n\n2. Create tunnel (for testing with Omi app):\n\n   ```bash\n   ngrok http 32768\n   ```\n\n3. Configure in Omi app:\n\n   ```bash\n   Webhook URL: https://[ngrok-url]/webhook?key=YOUR_SECRET\n   ```\n\n## Docker Details\n\n### Health Checks\n\n- 30-second interval checks\n- 3 retries before marking unhealthy\n- 5-second startup grace period\n- Automatic restart on failure\n\nMonitor health:\n\n```bash\ndocker ps\n# or\ndocker inspect webhook-server | grep -A 10 Health\n```\n\n## Security\n\n- URL key authentication\n- User ID validation\n- Input format validation\n- Proper error status codes (400, 401, 500)\n\n## Contributing\n\n1. Fork repository\n2. Create feature branch\n3. Run tests\n4. Submit pull request\n\n## License\n\nMIT License - see [LICENSE](LICENSE)\n\n## Acknowledgments\n\nSpecial thanks to [BasedHardware](https://github.com/BasedHardware) for creating the [Omi project](https://github.com/BasedHardware/omi).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthesethrose%2Fomi-webhook-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthesethrose%2Fomi-webhook-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthesethrose%2Fomi-webhook-server/lists"}