Event API

The Event API allows you to send notifications to your configured zones and groups. This is the core functionality of Notifery that lets you trigger notifications from your applications, services, or scripts.

Endpoint

POST /event

Authentication

Authentication is required for this endpoint and can be provided in one of two ways:

Via the x-api-key HTTP header (recommended)
Via the apiKey field in the request body

You can obtain an API key from your Notifery zone settings.

Request Body

Field	Type	Required	Description
`apiKey`	string	No*	Your API key (if not using the `x-api-key` header)
`title`	string	Yes	The title of your notification (1-255 characters)
`message`	string	No	The message body (default: empty string, max: 2048 characters)
`ttl`	integer	No	Time To Live in seconds (min: 60, max: 31536000 - 365 days)
`group`	string	No	The notification group identifier
`code`	integer	No	Status/error code (if applicable)
`duration`	integer	No	Duration in milliseconds (must be positive)
`icon`	string	No	Override the default icon for this notification
`iconColor`	string	No	Override the default color for this notification (hex color without #)

*Either the apiKey request body parameter or the x-api-key header must be provided.

Example Request

{
  "title": "Database Backup Completed",
  "message": "The nightly database backup completed successfully in 45 seconds",
  "group": "database-monitoring",
  "code": 0,
  "duration": 45,
  "icon": "database",
  "iconColor": "3498db"
}

Example Request with TTL

{
  "title": "Temporary Alert",
  "message": "This alert will automatically expire after 1 hour",
  "ttl": 3600,
  "group": "temporary-alerts"
}

Response

Success Response (201 Created)

{
  "message": "success",
  "id": "event-id-here"
}

Error Responses

Authentication Error (401 Unauthorized)

{
  "error": "Unauthorized"
}

Plan Limit Error (422 Unprocessable Entity)

{
  "error": "Plan limit exceeded" // Actual error message may vary
}

Server Error (500 Internal Server Error)

{
  "error": "Error message details"
}

Notes

JSON messages are automatically parsed and handled appropriately
Rate limiting is applied (20 requests per 20 seconds window)
Push notifications can be sent to zone members based on zone/group configuration
If code is greater than 0 and push notifications for errors are enabled, push notifications will be sent
You can override the default icon and color for a specific notification by setting the icon and iconColor fields
When using in scripts or command line, you can use the curl command:

curl -X POST https://api.notifery.com/event \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{"title": "Test Notification", "message": "This is a test message"}'

Time To Live (TTL)

The TTL feature allows you to set an automatic expiration time for individual events. This is useful for temporary notifications, time-sensitive alerts, or events that become irrelevant after a certain period.

How TTL Works

When you specify a ttl value in seconds, the event will automatically expire after that duration from its creation time
TTL must be between 60 seconds (1 minute) and 31,536,000 seconds (365 days)
Events with TTL will be automatically deleted once they expire
TTL works independently from your zone’s retention policy - events expire based on whichever comes first

Use Cases

Temporary Maintenance Alerts: Set a 1-hour TTL for maintenance notifications
Time-Sensitive Offers: Expire promotional events after their validity period
Short-Lived Status Updates: Auto-remove status updates that become stale quickly
Incident Notifications: Remove incident alerts once the expected resolution time passes

TTL vs Zone Retention

Feature	TTL	Zone Retention
Scope	Individual events	All events in zone
Configuration	Per API request	Zone settings
Range	60 seconds - 365 days	Based on plan
Priority	Expires when TTL is reached	Expires when retention period is reached

Events are deleted based on whichever expiration comes first - either the event’s TTL or the zone’s retention policy.

Push Notification Rules

Notifery provides a flexible notification system that allows configuration at both the zone level (default settings) and group level (overrides). Understanding how these settings interact is important for controlling when notifications are sent to your users.

Configuration Levels

Zone-Level Settings (Default)

In your zone settings page, you can configure two notification options:

Push Notifications Enabled: When enabled, all events sent to this zone will trigger push notifications.
Push Notifications for Errors Only: When enabled, only events with an error code (code > 0) will trigger push notifications. This setting is automatically disabled when general push notifications are enabled.

Group-Level Settings (Overrides)

Each group within a zone can have its own notification settings that override the zone defaults:

Push Notifications Enabled: Overrides the zone’s default push notification setting for this specific group.
Push Notifications for Errors Only: Overrides the zone’s error-specific notification setting for this group. This setting is automatically disabled when the group’s general push notifications are enabled.

Icon and Color Customization

Notifery allows customization of notification icons and colors at three levels, in order of precedence:

API Request Override: Set icon and iconColor in individual API requests for per-notification customization
Group Settings: Configure default icons and colors for specific notification groups
Zone Settings: Set global default icons and colors for the entire zone

If not specified at any level, Notifery will use the default icon and color.

Example Scenarios

Zone Settings	Group Settings	Event Type	Push Notification Sent?
All: ON Errors Only: N/A	Undefined	Any	Yes
All: OFF Errors Only: ON	Undefined	Normal	No
All: OFF Errors Only: ON	Undefined	Error	Yes
All: OFF Errors Only: OFF	All: ON Errors Only: N/A	Any	Yes
All: ON Errors Only: N/A	All: OFF Errors Only: ON	Normal	No
All: ON Errors Only: N/A	All: OFF Errors Only: ON	Error	Yes

This hierarchical configuration system gives you fine-grained control over which events trigger notifications at both zone and group levels.