Skip to main content

Publishing via HTTP

The simplest way to publish messages is using HTTP POST or PUT requests.

Basic Publishing​

POST Request​

curl -d "Your message here" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  https://app.notifer.io/your-topic

PUT Request​

echo "Your message" | curl -T - \
  -H "Authorization: Bearer YOUR_TOKEN" \
  https://app.notifer.io/your-topic

Both methods work identically - use whichever is more convenient.

Authentication Required

All examples below assume you have authentication configured. See Authentication section for details.

Message Parameters​

Add details to your messages using HTTP headers:

Title​

curl -d "Deployment completed successfully" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Title: Production Deploy" \
  https://app.notifer.io/deployments

Priority​

Set priority from 1 (critical) to 5 (info) using the X-Priority header. See Priority Levels for details.

curl -d "Server is down!" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Priority: 1" \
  https://app.notifer.io/alerts

Tags​

Add comma-separated tags using the X-Tags header. See Tags for details.

curl -d "Database connection lost" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tags: database,error,production" \
  https://app.notifer.io/alerts

Combined Parameters​

curl -d "CPU usage at 95%" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Title: Server Alert" \
  -H "X-Priority: 2" \
  -H "X-Tags: server,cpu,warning" \
  https://app.notifer.io/monitoring

Action Buttons​

Add clickable buttons to your messages. Two methods available:

Simple (single link):

curl -d "Build completed" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-URL: https://ci.example.com/builds/123" \
  -H "X-URL-Title: View Build" \
  https://app.notifer.io/ci-notifications

Advanced (multiple buttons):

curl -d "PR ready for review" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Actions: view, Approve, https://example.com/approve; view, Reject, https://example.com/reject" \
  https://app.notifer.io/reviews

See Action Buttons for full documentation including JSON format and HTTP actions.

Authentication​

All publishing requires authentication - even to public topics. Use one of three methods: JWT tokens, API keys, or topic access tokens.

# JWT Token (user authentication)
curl -d "Your message" \
  -H "Authorization: Bearer eyJhbGciOiJIUz..." \
  https://app.notifer.io/your-topic

# API Key (script authentication)
curl -d "Your message" \
  -H "X-API-Key: noti_your_key_here" \
  https://app.notifer.io/your-topic

# Topic Access Token (topic-scoped authentication)
curl -d "Your message" \
  -H "X-Topic-Token: tk_your_token_here" \
  https://app.notifer.io/your-topic
Learn more about authentication

For detailed explanations of each method, token creation, security best practices, and code examples in multiple languages, see Authentication.

Topics must exist before publishing

All topics must be created via the dashboard, API, or CLI before you can publish to them. Publishing to a non-existent topic returns a 404 error.

Public vs Private topics
  • Public topics: Anyone can read/subscribe, but publishing still requires authentication
  • Private topics: Both reading and publishing require authentication

Markdown Formatting​

Messages support Markdown:

curl -d "**Bold**, *italic*, \`code\`, and [links](https://example.com)" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  https://app.notifer.io/formatted-messages

Supported Markdown:

  • **bold** → bold
  • *italic* → italic
  • `code` → code
  • [link](url) → link
  • # Heading → Heading
  • - List item → List item
  • > Quote → Quote
  • ```code block``` → Code block

Response Format​

Success Response​

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "topic": "your-topic",
  "message": "Your message here",
  "title": "Optional Title",
  "priority": 3,
  "tags": ["tag1", "tag2"],
  "url": "https://example.com",
  "url_title": "Open Link",
  "actions": null,
  "timestamp": "2025-11-02T10:30:00Z"
}

Status code: 200 OK

Error Response​

{
  "detail": "Topic not found or access denied"
}

Common status codes:

  • 400 Bad Request - Invalid parameters
  • 401 Unauthorized - Missing or invalid authentication
  • 403 Forbidden - No permission to publish
  • 404 Not Found - Topic doesn't exist (for private topics)
  • 429 Too Many Requests - Rate limit exceeded

Real-World Examples​

Server Monitoring​

#!/bin/bash
# Check disk space and alert if > 80%
USAGE=$(df -h / | awk 'NR==2 {print $5}' | sed 's/%//')
if [ $USAGE -gt 80 ]; then
  curl -d "Disk usage at ${USAGE}%" \
    -H "X-Priority: 2" \
    -H "X-Tags: server,disk,warning" \
    https://app.notifer.io/server-alerts
fi

CI/CD Pipeline​

# GitHub Actions example
- name: Notify deployment
  run: |
    curl -d "Deployment to production completed" \
      -H "X-Title: Deploy Success" \
      -H "X-Tags: ci,deploy,production" \
      -H "X-Topic-Token: ${{ secrets.NOTIFER_TOPIC_TOKEN }}" \
      https://app.notifer.io/ci-notifications

Database Backup​

#!/bin/bash
# Backup database and notify
if pg_dump mydb > backup.sql; then
  curl -d "Database backup completed successfully" \
    -H "X-Title: Backup Success" \
    -H "X-Priority: 3" \
    -H "X-Tags: backup,database,success" \
    https://app.notifer.io/backups
else
  curl -d "Database backup FAILED!" \
    -H "X-Title: Backup Failed" \
    -H "X-Priority: 1" \
    -H "X-Tags: backup,database,error" \
    https://app.notifer.io/backups
fi

Log Monitoring​

# Alert on error in logs
tail -f /var/log/app.log | grep -i error | while read line; do
  curl -d "$line" \
    -H "X-Title: Application Error" \
    -H "X-Priority: 2" \
    -H "X-Tags: logs,error" \
    https://app.notifer.io/app-errors
done

Health Check​

#!/bin/bash
# Ping service and alert if down
if ! curl -sf https://myapp.com/health > /dev/null; then
  curl -d "Service health check failed!" \
    -H "X-Priority: 1" \
    -H "X-Tags: health,critical" \
    -H "X-Topic-Token: tk_your_token_here" \
    https://app.notifer.io/alerts
fi

Advanced Options​

Rate Limiting​

Respect rate limits by checking response headers:

curl -i -d "Message" https://app.notifer.io/topic

Response headers:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 1699000000

Retry Logic​

Implement exponential backoff for failed requests:

#!/bin/bash
MAX_RETRIES=3
RETRY_DELAY=1

for i in $(seq 1 $MAX_RETRIES); do
  if curl -d "Message" https://app.notifer.io/topic; then
    exit 0
  fi
  echo "Retry $i failed, waiting ${RETRY_DELAY}s"
  sleep $RETRY_DELAY
  RETRY_DELAY=$((RETRY_DELAY * 2))
done
echo "All retries failed"
exit 1

Next Steps​