Skip to main content

​
Overview

Sending events to PingPilot is simple: make a POST request to the events endpoint with your API key and event data. PingPilot will process the event and send notifications to all your configured channels (Discord, Telegram, Email).

​
API Endpoint

POST https://pingpilot.com/api/v1/event

​
Authentication

All requests must include your API key in the Authorization header as a Bearer token: 
Authorization: Bearer YOUR_API_KEY
Don’t have an API key yet? Find it in your dashboard settings.

​
Request Format

​
Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

​
Body Parameters

​
category
string
required
The name of the event category. Must match an existing category in your account.Validation: Must be lowercase and contain only letters, numbers, or hyphens.
​
description
string
A description of the event. If not provided, a default description will be generated.Default: "A new {category} event has occurred!"
​
fields
object
Additional data to include with the event. Keys must be strings, values can be strings, numbers, or booleans.Example: { "user_id": "12345", "amount": 99.99, "verified": true }

​
Basic Example

curl -X POST https://pingpilot.com/api/v1/event \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "bug",
    "description": "Critical error in payment processor"
  }'

​
Advanced Example with Fields

curl -X POST https://pingpilot.com/api/v1/event \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "sale",
    "description": "New premium plan purchase",
    "fields": {
      "customer_id": "cus_123456",
      "plan": "Premium",
      "amount": 99.99,
      "recurring": true,
      "trial": false
    }
  }'

​
Response Format

​
Success Response

{
  "message": "Event processed successfully",
  "eventId": "clxxx..."
}
Status Code: 200 OK The eventId can be used to track the event in your dashboard.

​
Error Responses

{
  "message": "Unauthorized"
}
Cause: No Authorization header provided.Solution: Add the Authorization header with your API key.
{
  "message": "Invalid auth header format. Expected: 'Bearer [API_KEY]'"
}
Cause: Authorization header is not in the correct format.Solution: Ensure header is formatted as Bearer YOUR_API_KEY.
{
  "message": "Invalid API key"
}
Cause: The provided API key doesn’t exist or is invalid.Solution: Verify your API key in the dashboard.
{
  "message": "Invalid JSON request body"
}
Cause: Request body is not valid JSON.Solution: Ensure your request body is properly formatted JSON.
{
  "message": "Please enter your discord ID in your account settings"
}
Cause: Your Discord ID is not configured.Solution: Add your Discord ID in account settings.
{
  "message": "Telegram username not set. Please set your telegram username in your account settings to receive notifications"
}
Cause: Your Telegram username is not configured.Solution: Add your Telegram username in account settings.
{
  "message": "You dont have a category named 'your-category'"
}
Cause: The specified category doesn’t exist in your account.Solution: Create the category first or check for typos.
{
  "message": "Validation error details..."
}
Cause: Request data doesn’t meet validation requirements.Solution: Check that:
  • category contains only letters, numbers, or hyphens
  • fields values are strings, numbers, or booleans
  • All required fields are present
{
  "message": "Monthly quota reached. Please upgrade your plan for more events"
}
Cause: You’ve reached your monthly event quota.Solution: Upgrade your plan or wait until next month.
{
  "message": "Error processing event",
  "eventId": "clxxx..."
}
Cause: Event was created but notification delivery failed.Solution: Check your notification settings and try again.

​
What Happens When You Send an Event?

When PingPilot receives an event:
1

Authentication

Your API key is validated against the database
2

Validation

  • Request body is validated
  • Category existence is checked
  • Quota limits are verified
3

Event Creation

Event is stored in the database with status PENDING
4

Notification Delivery

Notifications are sent to:
  • Discord: As an embedded message
  • Telegram: As a formatted text message
  • Email: As an HTML email
5

Status Update

Event status is updated to DELIVERED or FAILED
6

Quota Increment

Your monthly quota counter is incremented

​
Event Formatting

PingPilot formats your event data for each notification channel:

​
Discord Embed

{
  "title": "🐛 Bug",
  "description": "Critical error in payment processor",
  "color": 16738667,
  "timestamp": "2024-03-06T10:30:00.000Z",
  "fields": [
    {
      "name": "severity",
      "value": "high",
      "inline": true
    }
  ]
}

​
Telegram Message

🎉 Event Notification 🎉

📌 Category: 🐛 Bug
📝 Description: Critical error in payment processor
🎨 Color Code: 16738667
🕒 Timestamp: 2024-03-06T10:30:00.000Z

📌 Details:
🔹 severity: high

​
Email

HTML formatted email with:
  • Category title with emoji
  • Description
  • Color-coded visual elements
  • Timestamp
  • All custom fields in a table

​
Best Practices

Never hardcode your API key. Use environment variables:
# .env
PINGPILOT_API_KEY=your_api_key_here
Always handle API errors to prevent your application from crashing:
try {
  await sendEvent('bug', 'Error occurred')
} catch (error) {
  console.error('Failed to send event:', error)
  // Continue with your application logic
}
Provide meaningful descriptions and fields:✅ Good:
{
  "category": "payment-failed",
  "description": "Payment declined for subscription renewal",
  "fields": {
    "customer_id": "cus_123",
    "amount": 99.99,
    "reason": "insufficient_funds"
  }
}
❌ Bad:
{
  "category": "error",
  "description": "Something went wrong"
}
Avoid sending passwords, credit card numbers, or other sensitive information in event data.
For critical events, implement retry logic with exponential backoff:
async function sendEventWithRetry(data, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await sendEvent(data)
    } catch (error) {
      if (i === maxRetries - 1) throw error
      await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000))
    }
  }
}

​
Rate Limits & Quotas

PingPilot enforces monthly quotas based on your plan:
  • Free: 100 events/month
  • Pro: 1,000 events/month
  • Enterprise: Custom limits
Quotas reset on the first day of each month. There are no per-second or per-minute rate limits.

​
Testing Your Integration

Create a test category and send a test event: 
# Create a 'test' category in your dashboard first

curl -X POST https://pingpilot.com/api/v1/event \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "test",
    "description": "Testing PingPilot integration",
    "fields": {
      "environment": "development",
      "version": "1.0.0"
    }
  }'
You should receive notifications on all configured channels within seconds.

​
Next Steps

Managing Notifications

Configure your notification preferences

API Reference

View the complete API reference

Build docs developers (and LLMs) love

Get started for freeTalk to us