# 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]]