# Examples & Scenarios Real-world examples showing how to connect external tools to Zaphiri using the Inbox API. Each scenario walks through the setup, the webhook payload and the expected behaviour. > [!quote] Build it once > A 10-minute integration setup can save hours of manual task entry every week. --- ## Kindle Highlights: Daily Review Checklist > [!success] Featured integration > This is a real integration built by the Zaphiri team. A Cloudflare Worker pulls random Kindle highlights from your library each morning and delivers them as a checklist task in Zaphiri, so you start each day revisiting ideas from the books you've read. ### How It Works ``` Obsidian Vault (Kindle highlights as Markdown) ↓ Sync CLI pushes highlights to Cloudflare KV ↓ Daily cron (6:00 AM EST) selects 5 random highlights ↓ POST to Zaphiri webhook → grouped checklist task ``` 1. **Kindle highlights** are stored as Markdown files in an Obsidian vault (one file per book, with each highlight as a block) 2. A **sync CLI** reads the vault and uploads highlights to Cloudflare KV storage via an admin endpoint 3. A **daily cron trigger** (11:00 UTC) fires the Cloudflare Worker 4. The worker **selects 5 random highlights**, avoiding recently sent ones using a sent history tracker 5. It builds a Zaphiri webhook payload and **POSTs it to your integration's webhook URL** 6. Zaphiri receives the items, groups them into a single checklist task, and it shows up in your day ### Step 1: Create the Integration Set up a Zaphiri integration with auto-convert and grouping so highlights become a single checklist task automatically: ```bash curl -X POST https://tickup-api.mytickup.com/api/v1/integrations \ -H "Authorization: Bearer <jwt>" \ -H "Content-Type: application/json" \ -d '{ "name": "Kindle Highlights", "description": "Daily random highlights from my reading library", "template_config": { "date_mode": "today", "label": "reading", "auto_convert": true, "group_items": true, "group_title_template": "Daily Kindle Highlights", "list_style": "checklist", "energy": "low", "priority": "low" } }' ``` Save the `token` from the response. You'll need it for the worker. ### Step 2: Build the Cloudflare Worker The worker has three jobs: store highlights, select random ones each day and send them to Zaphiri. **`wrangler.toml`** ```toml name = "kindle-highlights" main = "src/index.ts" compatibility_date = "2025-01-01" [triggers] crons = ["0 11 * * *"] # 11:00 UTC = 6:00 AM EST [[kv_namespaces]] binding = "KINDLE_HIGHLIGHTS" id = "<your-kv-namespace-id>" [vars] DAILY_COUNT = "5" ``` **Secrets** (set via Wrangler CLI): ```bash npx wrangler secret put ADMIN_SECRET # Bearer token for admin endpoints npx wrangler secret put ZAPHIRI_INBOX_URL # Full webhook URL with token ``` ### Step 3: Sync Highlights from Obsidian The sync endpoint accepts a bulk upload of highlights parsed from your Obsidian vault: ```bash curl -X PUT https://kindle-highlights.<your-subdomain>.workers.dev/admin/sync \ -H "Authorization: Bearer <admin-secret>" \ -H "Content-Type: application/json" \ -d '{ "highlights": [ { "id": "h-001", "text": "The only way to do great work is to love what you do.", "source": "Steve Jobs", "author": "Walter Isaacson", "location": 1234 }, { "id": "h-002", "text": "Knowledge is not power. The implementation of knowledge is power.", "source": "The Compound Effect", "author": "Darren Hardy", "location": 892 } ], "full_sync": false }' ``` Set `full_sync: true` to remove highlights that aren't in the new set (useful for cleaning up deleted highlights from your vault). ### Step 4: The Daily Payload Each morning the cron fires and the worker sends this to Zaphiri: ```json { "title": "Daily Kindle Highlights", "items": [ { "text": "The only way to do great work is to love what you do.", "source": "Steve Jobs by Walter Isaacson (Location 1234)", "external_id": "h-001" }, { "text": "Knowledge is not power. The implementation of knowledge is power.", "source": "The Compound Effect by Darren Hardy (Location 892)", "external_id": "h-002" }, { "text": "Be yourself; everyone else is already taken.", "source": "The Importance of Being Earnest by Oscar Wilde (Location 3456)", "external_id": "h-003" }, { "text": "You do not rise to the level of your goals. You fall to the level of your systems.", "source": "Atomic Habits by James Clear (Location 412)", "external_id": "h-004" }, { "text": "The best time to plant a tree was 20 years ago. The second best time is now.", "source": "The Compound Effect by Darren Hardy (Location 2345)", "external_id": "h-005" } ] } ``` ### What Happens in Zaphiri Because the integration has `auto_convert`, `group_items`, and `list_style: "checklist"` enabled: - All 5 highlights are **grouped into a single Zaphiri task** titled "Daily Kindle Highlights" - Each highlight appears as a **checkbox item** in the task body, with the book title and author as attribution - The task lands on **today's date** with low energy and low priority, which suits a morning review - `external_id` on each item means **re-running the cron is safe**. Duplicates are silently skipped ### Random Selection & Repeat Avoidance The worker tracks which highlights have been sent in a `sent_history` list stored in KV: - Each day, it filters out recently sent highlights so you don't see the same ones back-to-back - It uses a **Fisher-Yates shuffle** on the remaining pool and picks the top 5 - When all highlights have been sent once, the history **resets automatically** and the cycle starts fresh - This means every highlight comes up once before any repeats, like a shuffled deck of cards ### Testing & Monitoring **Manual trigger** (bypasses the daily idempotency check): ```bash curl -X POST https://kindle-highlights.<your-subdomain>.workers.dev/admin/trigger \ -H "Authorization: Bearer <admin-secret>" ``` **Status check** (no auth required): ```bash curl https://kindle-highlights.<your-subdomain>.workers.dev/status ``` ```json { "total_highlights": 156, "unique_books": 8, "last_sync": "2026-02-17T14:32:15Z", "last_sent": "2026-02-18", "sent_today": true } ``` You can also use Zaphiri's **Test Webhook** button in Settings > API to trigger a test payload through the integration, or check the [[API-Reference/Integrations#Get Webhook Logs|webhook logs]] for delivery history. --- ## GitHub: Auto-Import Issues Send new GitHub issues to your Zaphiri Inbox using GitHub Webhooks. ### Setup 1. [[API-Reference/Integrations#Create Integration|Create an integration]] named "GitHub Issues": ```bash curl -X POST https://tickup-api.mytickup.com/api/v1/integrations \ -H "Authorization: Bearer <jwt>" \ -H "Content-Type: application/json" \ -d '{ "name": "GitHub Issues", "description": "New issues from my-org repos", "template_config": { "date_mode": "today", "label": "github", "priority": "medium", "energy": "medium" } }' ``` 2. Copy the `token` from the response 3. In your GitHub repo, go to **Settings > Webhooks > Add webhook** 4. Set the Payload URL to `https://tickup-api.mytickup.com/api/v1/inbox/<your-token>` 5. Set Content type to `application/json` 6. Select "Let me select individual events" and check **Issues** ### Webhook Relay Script GitHub's webhook format doesn't match the Zaphiri payload schema directly. Use a lightweight relay (Cloudflare Worker, AWS Lambda or similar) to transform the payload: ```javascript // Example: Cloudflare Worker relay export default { async fetch(request) { const github = await request.json(); // Only process newly opened issues if (github.action !== "opened") { return new Response("skipped", { status: 200 }); } const payload = { items: [ { text: github.issue.title, source: `github/${github.repository.full_name}`, external_id: `gh-issue-${github.issue.id}` } ], metadata: { issue_number: github.issue.number, url: github.issue.html_url, labels: github.issue.labels.map(l => l.name) } }; return fetch("https://tickup-api.mytickup.com/api/v1/inbox/YOUR_TOKEN", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(payload) }); } }; ``` ### What Happens - Each new issue creates one pending Inbox item - The `external_id` (`gh-issue-${id}`) prevents duplicates if the webhook fires twice - Items inherit the integration defaults: today's date, "github" label, medium priority - Review them in your Inbox and convert them to Zaphiri tasks when ready --- ## Todoist: Daily Task Sync Sync your Todoist tasks into Zaphiri at the start of each day using a scheduled automation. ### Setup 1. Create an integration with auto-convert and grouping enabled: ```bash curl -X POST https://tickup-api.mytickup.com/api/v1/integrations \ -H "Authorization: Bearer <jwt>" \ -H "Content-Type: application/json" \ -d '{ "name": "Todoist Daily Sync", "template_config": { "date_mode": "today", "label": "todoist", "auto_convert": true, "group_items": true, "group_title_template": "Todoist - {{date}} ({{count}} tasks)", "list_style": "checklist" } }' ``` ### Automation Script Run this daily via cron, GitHub Actions, or any scheduler: ```bash #!/bin/bash # Fetch today's Todoist tasks and send to Zaphiri TODOIST_TOKEN="your_todoist_api_token" ZAPHIRI_TOKEN="your_integration_token" # Get tasks due today from Todoist TASKS=$(curl -s "https://api.todoist.com/rest/v2/tasks?filter=today" \ -H "Authorization: Bearer $TODOIST_TOKEN") # Transform to Zaphiri payload PAYLOAD=$(echo "$TASKS" | python3 -c " import sys, json tasks = json.load(sys.stdin) items = [ { 'text': t['content'], 'source': 'todoist', 'external_id': f\"todoist-{t['id']}\" } for t in tasks ] print(json.dumps({'items': items})) ") # Send to Zaphiri curl -X POST "https://tickup-api.mytickup.com/api/v1/inbox/$ZAPHIRI_TOKEN" \ -H "Content-Type: application/json" \ -d "$PAYLOAD" ``` ### What Happens - All tasks are grouped into a single Zaphiri task with a checklist - The task title reads something like "Todoist - Feb 18, 2026 (7 tasks)" - Each Todoist task becomes a checkbox item in the task body - Deduplication by `external_id` means re-running the script is safe - Because `auto_convert` is on, items skip the Inbox and become a task straight away --- ## Slack: Save Messages as Tasks Turn Slack messages into Zaphiri Inbox items using Slack's workflow builder or a custom Slack app. ### Setup 1. Create an integration: ```bash curl -X POST https://tickup-api.mytickup.com/api/v1/integrations \ -H "Authorization: Bearer <jwt>" \ -H "Content-Type: application/json" \ -d '{ "name": "Slack Saves", "template_config": { "date_mode": "today", "label": "slack", "energy": "low", "priority": "low" } }' ``` 2. In Slack, create a shortcut or workflow that sends a POST request when triggered ### Payload Example When someone saves a message via your Slack shortcut: ```bash curl -X POST https://tickup-api.mytickup.com/api/v1/inbox/YOUR_TOKEN \ -H "Content-Type: application/json" \ -d '{ "items": [ { "text": "Look into the deployment issue Sarah mentioned", "source": "slack/#engineering" } ], "metadata": { "channel": "engineering", "sender": "sarah.jones", "timestamp": "2026-02-18T14:30:00Z" } }' ``` ### What Happens - The message is saved to your Inbox with the "slack" label and low energy and priority - Metadata preserves the channel and sender for context - Review and convert during your next triage session --- ## Email Forwarding Service: Inbox via Email Use an email-to-webhook service (like Zapier, Make, or a custom mail processor) to turn forwarded emails into Inbox items. ### Setup 1. Create an integration: ```bash curl -X POST https://tickup-api.mytickup.com/api/v1/integrations \ -H "Authorization: Bearer <jwt>" \ -H "Content-Type: application/json" \ -d '{ "name": "Email Inbox", "template_config": { "date_mode": "today", "label": "email", "priority": "medium" } }' ``` 2. Configure your email-to-webhook service to POST to `https://tickup-api.mytickup.com/api/v1/inbox/<token>` ### Payload Example ```bash curl -X POST https://tickup-api.mytickup.com/api/v1/inbox/YOUR_TOKEN \ -H "Content-Type: application/json" \ -d '{ "title": "Email Action Items", "items": [ { "text": "Reply to vendor about Q2 pricing", "source": "email/[email protected]", "external_id": "email-msg-abc123" }, { "text": "Schedule follow-up with design team", "source": "email/[email protected]", "external_id": "email-msg-def456" } ] }' ``` --- ## CI/CD: Post-Deploy Tasks Create follow-up tasks automatically after deployments, using your CI/CD pipeline. ### GitHub Actions Example Add this step to your deployment workflow: ```yaml # .github/workflows/deploy.yml - name: Create post-deploy tasks in Zaphiri if: success() run: | curl -X POST https://tickup-api.mytickup.com/api/v1/inbox/${{ secrets.ZAPHIRI_WEBHOOK_TOKEN }} \ -H "Content-Type: application/json" \ -d '{ "title": "Post-Deploy: v${{ github.ref_name }}", "items": [ {"text": "Verify staging deployment is healthy", "source": "github-actions"}, {"text": "Run smoke tests against staging", "source": "github-actions"}, {"text": "Check error monitoring for new issues", "source": "github-actions"}, {"text": "Update release notes", "source": "github-actions"} ], "overrides": { "priority": "high", "energy": "medium", "date": "'"$(date +%Y-%m-%d)"'" } }' ``` ### What Happens - After a successful deploy, four follow-up tasks land in your Inbox - Priority is set to high with today's date via overrides - You can convert them individually or bulk-convert all at once --- ## Meeting Notes: Bulk Action Items After a meeting, batch-send all action items from your notes to Zaphiri. ### Payload Example ```bash curl -X POST https://tickup-api.mytickup.com/api/v1/inbox/YOUR_TOKEN \ -H "Content-Type: application/json" \ -d '{ "title": "Team Standup - Feb 18", "items": [ {"text": "Update project timeline with new milestones", "source": "meeting/standup"}, {"text": "Review PR #87 before EOD", "source": "meeting/standup"}, {"text": "Set up monitoring for new payment endpoint", "source": "meeting/standup"}, {"text": "Draft proposal for Q3 budget review", "source": "meeting/standup"} ], "overrides": { "date": "2026-02-18", "energy": "high" } }' ``` ### Bulk Triage After items land in your Inbox, use bulk actions to process them quickly: ```bash # List pending items curl -X GET https://tickup-api.mytickup.com/api/v1/inbox \ -H "Authorization: Bearer <jwt>" # Dismiss items you don't need curl -X POST https://tickup-api.mytickup.com/api/v1/inbox/bulk \ -H "Authorization: Bearer <jwt>" \ -H "Content-Type: application/json" \ -d '{ "ids": ["<item-id-1>", "<item-id-2>"], "action": "dismiss" }' # Convert the rest to tasks curl -X POST https://tickup-api.mytickup.com/api/v1/inbox/bulk \ -H "Authorization: Bearer <jwt>" \ -H "Content-Type: application/json" \ -d '{ "ids": ["<item-id-3>", "<item-id-4>"], "action": "convert" }' ``` --- ## iOS Shortcuts: Quick Capture Use Apple Shortcuts to send tasks to Zaphiri from your iPhone with a single tap. ### Shortcut Setup Create a shortcut with these actions: 1. **Ask for Input**: prompt: "What do you need to do?" 2. **Get Contents of URL**: - URL: `https://tickup-api.mytickup.com/api/v1/inbox/YOUR_TOKEN` - Method: POST - Headers: `Content-Type: application/json` - Body (JSON): ```json { "items": [ { "text": "[Shortcut Input]", "source": "ios-shortcut" } ] } ``` 3. **Show Notification**: "Added to Zaphiri inbox" ### What Happens - Tap the shortcut, type your task, and it lands in your Zaphiri Inbox - Works from your home screen, share sheet, or Siri - Items are tagged with the "ios-shortcut" source so they're easy to spot --- ## Zapier / Make: No-Code Integration Connect any app to Zaphiri without writing code using Zapier or Make (Integromat). ### Zapier Setup 1. Create a new Zap with your trigger app (for example "New email in Gmail" or "New row in Google Sheets") 2. Add a **Webhooks by Zapier** action step 3. Configure: - Method: POST - URL: `https://tickup-api.mytickup.com/api/v1/inbox/YOUR_TOKEN` - Payload Type: JSON - Data: | Key | Value | |-----|-------| | `items[0][text]` | Map from trigger data | | `items[0][source]` | `zapier/gmail` (or your trigger name) | | `items[0][external_id]` | Map a unique ID from trigger | ### Make (Integromat) Setup 1. Create a scenario with your trigger module 2. Add an **HTTP > Make a request** module 3. Configure: - URL: `https://tickup-api.mytickup.com/api/v1/inbox/YOUR_TOKEN` - Method: POST - Body type: Raw (JSON) - Content: ```json { "items": [ { "text": "{{trigger.field}}", "source": "make/google-sheets", "external_id": "{{trigger.id}}" } ] } ``` --- ## Integration Management Scenarios ### Rotate a Compromised Token If a token is leaked (for example committed to a public repo): ```bash # 1. Immediately rotate the token curl -X POST https://tickup-api.mytickup.com/api/v1/integrations/<id>/rotate \ -H "Authorization: Bearer <jwt>" # 2. Copy the new token from the response # 3. Update your external service with the new token # 4. Check logs for unauthorized access curl -X GET "https://tickup-api.mytickup.com/api/v1/integrations/<id>/logs?limit=50" \ -H "Authorization: Bearer <jwt>" ``` The old token stops working straight away. Any requests using it return `401`. ### Temporarily Disable an Integration Pause an integration without deleting it: ```bash # Disable curl -X PUT https://tickup-api.mytickup.com/api/v1/integrations/<id> \ -H "Authorization: Bearer <jwt>" \ -H "Content-Type: application/json" \ -d '{"is_active": false}' # Re-enable later curl -X PUT https://tickup-api.mytickup.com/api/v1/integrations/<id> \ -H "Authorization: Bearer <jwt>" \ -H "Content-Type: application/json" \ -d '{"is_active": true}' ``` While disabled, the webhook token still exists but all incoming webhooks return `401 invalid_token`. ### Monitor Integration Health Check if an integration is receiving data: ```bash # Get integration details - check last_received_at curl -X GET https://tickup-api.mytickup.com/api/v1/integrations/<id> \ -H "Authorization: Bearer <jwt>" # Review recent delivery logs for errors curl -X GET "https://tickup-api.mytickup.com/api/v1/integrations/<id>/logs?limit=10" \ -H "Authorization: Bearer <jwt>" ``` > [!tip] Debugging failed deliveries > Check the `status` field in webhook logs: > - `success`: payload accepted and items stored > - `validation_failed`: payload didn't pass validation (check `error_message` for details) > - `error`: internal processing error ### Test Before Going Live Use the test endpoint to check your integration works before you connect the real source: ```bash # Send a test payload through the pipeline curl -X POST https://tickup-api.mytickup.com/api/v1/integrations/<id>/test \ -H "Authorization: Bearer <jwt>" ``` This creates a test Inbox item without needing an external service. Check your Inbox to confirm it arrived. --- **Previous:** [[API-Reference/Inbox|Inbox]] | **Start:** [[API-Reference/API-Reference|API Reference]]