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)
`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"
}

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"}'

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.