Pushi Documentation

Multi-Channel

Pushi is a comprehensive multi-tenant SaaS platform designed for companies that need reliable, scalable notification delivery across multiple channels. Send notifications to Pushover, Discord, Slack, and Mattermost with a single API call.

For Companies
  • ✅ Complete data isolation between workspaces
  • ✅ Role-based access control
  • ✅ Enterprise security features
  • ✅ Subscription-based billing
  • ✅ Team collaboration tools
For Developers
  • ✅ RESTful API with comprehensive documentation
  • ✅ Code examples in 5+ programming languages
  • ✅ Webhook authentication
  • ✅ Rate limiting and usage analytics
  • ✅ Detailed error responses
Channel Availability: Free plans include Pushover + Slack. Pro and Enterprise plans unlock Discord and Mattermost integration.

Quick Start Guide

Get up and running with Pushi in just a few minutes.

Step 1: Create Your Account

Sign up for a free account to get started with basic Pushover and Slack notifications.

Sign Up Now
Step 2: Create a Workspace

Workspaces provide complete data isolation. Each workspace has its own:

  • Notification settings and tokens
  • User groups and permissions
  • API authentication hash
  • Usage analytics and billing
Step 3: Configure Notification Channels

Set up your preferred notification channels:

📱
Pushover
Add your Pushover app token to the workspace
💬
Slack
Configure incoming webhook URL
Step 4: Send Your First Notification

Use your workspace API hash to send notifications:

curl -X POST https://your-domain.com/api/notify \
  -H "Content-Type: application/json" \
  -H "X-Workspace-Hash: your-workspace-hash" \
  -d '{
    "message": "Hello from Pushi!",
    "title": "Test Notification"
  }'

Authentication

Pushi uses workspace-based authentication for API access. Each workspace has a unique hash that serves as the authentication token.

Authentication Header
X-Workspace-Hash: your-64-character-workspace-hash
Security Note: Keep your workspace hash secure. It provides full access to send notifications to your workspace. You can regenerate it anytime from the workspace settings.

Finding Your Workspace Hash

  1. Log into your dashboard
  2. Select your workspace
  3. Go to Workspace Settings
  4. Copy the API Hash from the API section

Workspaces

Workspaces are the foundation of Pushi's multi-tenant architecture. They provide complete isolation between different organizations, projects, or teams.

Key Features

Data Isolation

Each workspace maintains separate user lists, notification settings, and usage analytics.

Independent Billing

Each workspace has its own subscription plan and billing cycle.

Role-Based Access

Users can have different roles (Owner, Admin, Member, Viewer) in each workspace.

Custom Settings

Configure notification channels, webhook settings, and group permissions per workspace.

Workspace Limits

Plan Workspaces per User Members per Workspace Groups per Workspace
Free 1 5 3
Pro 5 25 10
Enterprise Unlimited Unlimited Unlimited

Groups

Groups allow you to organize users within a workspace for targeted notifications. Each group can have its own notification settings or inherit from the workspace.

Group Features

  • Targeted Messaging: Send notifications to specific groups instead of the entire workspace
  • Custom Webhooks: Override workspace webhook settings per group
  • Flexible Membership: Users can belong to multiple groups
  • Inheritance: Groups can inherit workspace notification settings or define their own

Group Configuration

Groups can be configured in two ways:

Inherit from Workspace

Use the workspace's notification channels and settings. This is the default and recommended approach.

Recommended
Custom Settings

Define group-specific webhook URLs and notification preferences for specialized use cases.

Advanced

Notification Channels

Pushi supports multiple notification channels, allowing you to reach your team wherever they are.

📱 Pushover All Plans

Real-time push notifications to mobile devices and desktop.

  • ✅ iOS and Android apps
  • ✅ Desktop notifications
  • ✅ Priority levels and sounds
  • ✅ Device targeting
  • ✅ Delivery confirmation
💬 Slack All Plans

Send messages to Slack channels and direct messages.

  • ✅ Channel and DM support
  • ✅ Rich message formatting
  • ✅ Custom bot names and icons
  • ✅ Thread replies
  • ✅ Mention support
🎮 Discord Pro+

Rich embeds and messages for Discord servers.

  • ✅ Rich embed support
  • ✅ Custom avatars and usernames
  • ✅ Color-coded messages
  • ✅ Mention and role pings
  • ✅ File attachments
💼 Mattermost Pro+

Self-hosted team communication platform integration.

  • ✅ On-premise compatibility
  • ✅ Channel and DM support
  • ✅ Custom bot configuration
  • ✅ Markdown formatting
  • ✅ File attachments
Channel Targeting: You can send notifications to specific channels by including a "channels" array in your API request. Omit this parameter to send to all configured channels.

API Overview

The Pushi API is built on REST principles with predictable URLs, standard HTTP response codes, and JSON payloads.

Base URL
https://pushi.app/api

HTTP Response Codes

Code Description Meaning
200 OK Request successful
400 Bad Request Invalid request parameters
401 Unauthorized Invalid or missing workspace hash
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error occurred

Send Notifications

Send notifications to all users in a workspace across all configured channels.

POST /api/notify
Headers
Content-Type: application/json
X-Workspace-Hash: your-workspace-hash
Request Body
{
  "message": "Your notification message",
  "title": "Optional title",
  "priority": 0,
  "channels": ["pushover", "slack"]
}
Parameters
Parameter Type Required Description
message string Yes The notification message (max 1024 characters)
title string No Optional title (max 250 characters)
priority integer No Priority level: -2 (lowest) to 2 (emergency)
channels array No Specific channels to target. Omit for all channels.
Response
{
  "success": true,
  "message": "Notification sent successfully",
  "statistics": {
    "pushover_success_count": 5,
    "pushover_error_count": 0,
    "webhook_success_count": 2,
    "webhook_error_count": 0,
    "total_channels": 3
  }
}
Code Examples

Use your workspace hash to authenticate API requests. You can include it in the header, URL, or as a query parameter.
New: Use the optional channels parameter to target specific notification channels (pushover, discord, slack, mattermost). If omitted, all configured channels receive the notification.

#!/bin/bash

# Using header authentication
curl -X POST "https://pushi.app/api/notify" \
  -H "Content-Type: application/json" \
  -H "X-Workspace-Hash: YOUR_WORKSPACE_HASH" \
  -d '{
    "message": "Hello from Pushi App API!",
    "title": "Important Notification",
    "priority": 0,
    "sound": "pushover",
    "url": "https://example.com/details",
    "url_title": "View Details",
    "channels": [
        "pushover",
        "slack"
    ]
}'
# Alternative: Using query parameter
curl -X POST "https://pushi.app/api/notify?workspace_hash=YOUR_WORKSPACE_HASH" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello from Pushi App API!",
    "title": "Important Notification",
    "priority": 0,
    "sound": "pushover",
    "url": "https://example.com/details",
    "url_title": "View Details",
    "channels": [
        "pushover",
        "slack"
    ]
}'
<?php
// Using cURL
$ch = curl_init('https://pushi.app/api/notify');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-Workspace-Hash: YOUR_WORKSPACE_HASH'
]);
$payload = {
    "message": "Hello from Pushi App API!",
    "title": "Important Notification",
    "priority": 0,
    "sound": "pushover",
    "url": "https://example.com/details",
    "url_title": "View Details",
    "channels": [
        "pushover",
        "slack"
    ]
};
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($response, true);
if ($httpCode === 200) {
    echo "Success: " . $result['message'] . "\n";
    echo "Notified: " . $result['data']['statistics']['successful_deliveries'] . " users\n";
} else {
    echo "Error: " . $result['error'] . "\n";
}

// Alternative: Using file_get_contents
$options = [
    'http' => [
        'method' => 'POST',
        'header' => [
            'Content-Type: application/json',
            'X-Workspace-Hash: YOUR_WORKSPACE_HASH'
        ],
        'content' => json_encode({
    "message": "Hello from Pushi App API!",
    "title": "Important Notification",
    "priority": 0,
    "sound": "pushover",
    "url": "https://example.com/details",
    "url_title": "View Details",
    "channels": [
        "pushover",
        "slack"
    ]
})    ]
];

$context = stream_context_create($options);
$response = file_get_contents('https://pushi.app/api/notify', false, $context);
$result = json_decode($response, true);
// Using Fetch API (Modern Browsers & Node.js 18+)
const sendNotification = async () => {
    try {
        const response = await fetch('https://pushi.app/api/notify', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'X-Workspace-Hash': 'YOUR_WORKSPACE_HASH'
            },
            body: JSON.stringify({
    "message": "Hello from Pushi App API!",
    "title": "Important Notification",
    "priority": 0,
    "sound": "pushover",
    "url": "https://example.com/details",
    "url_title": "View Details",
    "channels": [
        "pushover",
        "slack"
    ]
})        });

        const result = await response.json();
        
        if (response.ok) {
            console.log('Success:', result.message);
            console.log(`Notified ${result.data.statistics.successful_deliveries} users`);
        } else {
            console.error('Error:', result.error);
        }
    } catch (error) {
        console.error('Network error:', error);
    }
};

sendNotification();

// Using Axios (requires: npm install axios)
const axios = require('axios');

axios.post('https://pushi.app/api/notify', {
    "message": "Hello from Pushi App API!",
    "title": "Important Notification",
    "priority": 0,
    "sound": "pushover",
    "url": "https://example.com/details",
    "url_title": "View Details",
    "channels": [
        "pushover",
        "slack"
    ]
}, {
    headers: {
        'Content-Type': 'application/json',
        'X-Workspace-Hash': 'YOUR_WORKSPACE_HASH'
    }
})
.then(response => {
    console.log('Success:', response.data.message);
    console.log(`Notified ${response.data.data.statistics.successful_deliveries} users`);
})
.catch(error => {
    console.error('Error:', error.response?.data?.error || error.message);
});
#!/usr/bin/env python3
import requests
import json

# API endpoint and authentication
url = 'https://pushi.app/api/notify'
headers = {
    'Content-Type': 'application/json',
    'X-Workspace-Hash': 'YOUR_WORKSPACE_HASH'
}

# Notification payload
payload = {
    "message": "Hello from Pushi App API!",
    "title": "Important Notification",
    "priority": 0,
    "sound": "pushover",
    "url": "https://example.com/details",
    "url_title": "View Details",
    "channels": [
        "pushover",
        "slack"
    ]
}

# Send the request
response = requests.post(url, json=payload, headers=headers)

# Handle the response
if response.status_code == 200:
    result = response.json()
    print(f"Success: {result['message']}")
    stats = result['data']['statistics']
    print(f"Notified {stats['successful_deliveries']} users")
else:
    error = response.json()
    print(f"Error {response.status_code}: {error.get('error', 'Unknown error')}")

# Alternative: Using urllib (built-in)
import urllib.request
import urllib.error

data = json.dumps(payload).encode('utf-8')
req = urllib.request.Request(
    url,
    data=data,
    headers=headers,
    method='POST'
)

try:
    with urllib.request.urlopen(req) as response:
        result = json.loads(response.read().decode())
        print(f"Success: {result['message']}")
except urllib.error.HTTPError as e:
    error = json.loads(e.read().decode())
    print(f"Error {e.code}: {error.get('error', 'Unknown error')}")
#!/usr/bin/perl
use strict;
use warnings;
use LWP::UserAgent;
use JSON;
use HTTP::Request;

# Create user agent
my $ua = LWP::UserAgent->new;
$ua->timeout(10);

# API endpoint
my $url = 'https://pushi.app/api/notify';

# Create request
my $req = HTTP::Request->new('POST' => $url);
$req->header('Content-Type' => 'application/json');
$req->header('X-Workspace-Hash' => 'YOUR_WORKSPACE_HASH');

# Set request body
my $payload = {
    "message": "Hello from Pushi App API!",
    "title": "Important Notification",
    "priority": 0,
    "sound": "pushover",
    "url": "https://example.com/details",
    "url_title": "View Details",
    "channels": [
        "pushover",
        "slack"
    ]
};
$req->content(encode_json($payload));

# Send request
my $response = $ua->request($req);

# Handle response
if ($response->is_success) {
    my $result = decode_json($response->content);
    print "Success: $result->{message}\n";
    my $stats = $result->{data}->{statistics};
    print "Notified $stats->{successful_deliveries} users\n";
} else {
    my $error = decode_json($response->content);
    print "Error: $error->{error}\n";
}

# Alternative: Using curl command
my $workspace_hash = 'YOUR_WORKSPACE_HASH';
my $json_payload = encode_json({
    "message": "Hello from Pushi App API!",
    "title": "Important Notification",
    "priority": 0,
    "sound": "pushover",
    "url": "https://example.com/details",
    "url_title": "View Details",
    "channels": [
        "pushover",
        "slack"
    ]
});
my $cmd = qq{curl -X POST "$url" -H "Content-Type: application/json" -H "X-Workspace-Hash: $workspace_hash" -d '$json_payload'};

my $output = `$cmd 2>/dev/null`;
my $result = decode_json($output);

if ($result->{success}) {
    print "Success: $result->{message}\n";
} else {
    print "Error: $result->{error}\n";
}
Security Note: Keep your workspace hash secret. Treat it like a password and never commit it to public repositories.

Group Notifications

Send targeted notifications to specific groups within your workspace.

POST /api/groups/{group_id}/notify
URL Parameters
Parameter Description
group_id The group's hashid (found in dashboard)
Multiple Groups

Send to multiple groups by providing group IDs in the request body:

{
  "message": "Server maintenance in 30 minutes",
  "title": "Maintenance Alert",
  "groups": ["abc123", "def456", "ghi789"],
  "channels": ["pushover", "discord"]
}

Rate Limits

API rate limits are enforced per workspace with both daily and hourly (burst) limits to prevent abuse while ensuring fair usage.

Plan Daily Requests Hourly Burst Limit
Free 100 10 per hour
Pro 1,000 100 per hour
Enterprise 10,000 1,000 per hour
Rate Limiting: Daily limits reset at midnight UTC. Hourly burst limits (10% of daily limit) prevent API abuse and reset every hour. When either limit is exceeded, requests are blocked until the respective reset time.

Rate Limit Headers

All API responses include rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1640995200
X-RateLimit-Burst-Limit: 10
X-RateLimit-Burst-Remaining: 9

Pushover Setup

Pushover provides real-time notifications to iOS, Android, and desktop devices.

1. Create Pushover Application
  1. Visit pushover.net/apps/build
  2. Create a new application
  3. Copy your App Token (30 characters)
  4. Add the token to your workspace settings
2. User Configuration
  1. Users install Pushover app on their devices
  2. Users add their User Key to their profile
  3. Users can select specific devices or "all devices"
  4. Notifications are delivered instantly
Priority Levels: Pushover supports priority levels from -2 (silent) to 2 (emergency with confirmation required).

Discord Setup Pro+

Send rich embeds and messages to Discord servers and channels.

Creating Discord Webhooks
  1. Open Discord and navigate to your server
  2. Right-click on the channel → Edit Channel
  3. Go to Integrations → Webhooks → New Webhook
  4. Customize the name and avatar (optional)
  5. Copy the Webhook URL
  6. Add the URL to your workspace or group settings
Permissions: Ensure the webhook has permission to send messages in the target channel.

Slack Setup

Integrate with Slack channels and direct messages using incoming webhooks.

Setting up Slack Webhooks
  1. Go to api.slack.com/apps
  2. Create a new app or select existing one
  3. Navigate to Incoming Webhooks
  4. Activate incoming webhooks
  5. Add New Webhook to Workspace
  6. Select the channel and authorize
  7. Copy the webhook URL to your workspace settings

Mattermost Setup Pro+

Connect to self-hosted or cloud Mattermost instances.

Mattermost Webhook Configuration
  1. Log into your Mattermost instance
  2. Go to Main Menu → Integrations
  3. Select Incoming Webhooks
  4. Click Add Incoming Webhook
  5. Configure the webhook settings
  6. Copy the webhook URL
  7. Add to your workspace or group settings

Security

Pushi implements enterprise-grade security measures to protect your data and communications.

Authentication
  • Workspace-based API authentication
  • 64-character secure hash tokens
  • Token regeneration capability
  • Request rate limiting
Data Protection
  • Complete workspace data isolation
  • Encrypted sensitive data storage
  • GDPR-compliant data export/deletion
  • Secure session management
User Security
  • Two-factor authentication (2FA)
  • Password strength requirements
  • Session timeout and management
  • Login attempt monitoring
Infrastructure
  • SSL/TLS encryption in transit
  • Regular security updates
  • Comprehensive audit logging
  • 99.9% uptime SLA

Troubleshooting

Common issues and their solutions.

  1. Check workspace configuration: Ensure your Pushover app token is correctly configured
  2. Verify user tokens: Users must add their Pushover user tokens to their profiles
  3. Test webhook URLs: Use the test buttons in workspace settings to verify webhook connectivity
  4. Check rate limits: Ensure you haven't exceeded your daily API quota
  5. Review error logs: Check the API response for specific error messages

  1. Verify workspace hash: Ensure you're using the correct 64-character hash
  2. Check header format: Use X-Workspace-Hash header name
  3. Workspace status: Ensure the workspace is active and not suspended
  4. Regenerate hash: Try regenerating the workspace hash if issues persist

  1. Test webhook URLs: Verify URLs are accessible and return 200 status
  2. Check permissions: Ensure webhooks have proper channel permissions
  3. Validate URL format: Confirm webhook URLs are properly formatted
  4. Review webhook settings: Check custom username and channel configurations
Need Help? Contact our support team for additional assistance.