Skip to content
TipOff

Introduction

TipOff is a push notification gateway with actionable buttons and callback delivery. Send notifications from any source, receive user actions back via webhooks, gRPC streaming, SSE, or polling.

What it does

Section titled “What it does”
sequenceDiagram
    participant Source as Your Service
    participant API as api.tipoff.dev
    participant APNs as Apple APNs
    participant Device as iOS Device
    participant Delivery as Agent / SSE / Webhook

    Source->>API: POST /v1/notifications
    API->>APNs: Push (HTTP/2 + JWT)
    APNs->>Device: Notification with action buttons

    alt User taps an action
        Device->>API: POST /v1/notifications/{id}/actions
        API->>Delivery: Action event callback
    else Source completes the notification
        Source->>API: POST /v1/notifications/{id}/actions (sk_)
        API->>APNs: Silent push (remove notification)
        API->>Delivery: Completion event
    end
  1. You send a notification via the REST API (api.tipoff.dev) with a title, body, and action category
  2. TipOff delivers it to the user’s iOS device via APNs with interactive action buttons
  3. The user taps an action (e.g. “Done”, “Snooze”, “Dismiss”)
  4. TipOff delivers the callback to your agent, SSE stream, webhook, or polling endpoint

TipOff owns the delivery pipeline. It does not poll upstream services or transform source-specific data. Integration logic lives in external tools (n8n workflows, custom scripts, or the included agent binary with YAML adapters).

How you integrate

Section titled “How you integrate”

The TipOff server is hosted at api.tipoff.dev — it holds the Apple APNs credentials and handles push delivery. You integrate via one of two paths:

PathHow it worksBest for
AgentSelf-host the tipoff-agent binary. It connects to the server via gRPC, receives action events in real time, and forwards them to local services via YAML adapters.Always-on delivery with rich routing logic (e.g. mapping “Done” → Vikunja task completion API call)
Direct RESTCall the API directly — send notifications via POST /v1/notifications, receive callbacks via SSE, webhooks, or polling.Workflow engines (n8n, Home Assistant), simple integrations, anything that speaks HTTP

Both paths use the same hosted API. The agent is an optional convenience for users who want local action routing without writing HTTP glue.

Components

Section titled “Components”
ComponentWhere it runsPurpose
tipoff-serverHosted (api.tipoff.dev)REST API, push delivery via APNs, action callback routing
tipoff-agentSelf-hosted (optional)gRPC-to-HTTP proxy with YAML adapter system for local action delivery
tipoff-iosUser’s deviceiOS app that receives notifications and reports actions

Action delivery methods

Section titled “Action delivery methods”
MethodRequires agent?Best for
gRPC AgentYesAlways-on bidirectional streaming with local forwarding and YAML adapter routing
SSENoWorkflow engines (n8n SSE trigger), EventSource clients, real-time without a binary
WebhookNoDirect HTTP callbacks to your endpoint (HMAC-signed)
PollingNoSimple cron-based integrations

Next steps

Section titled “Next steps”