Notification Relay API Documentation

Base URL: https://notifications.phenixrts.app

Quick Start Guide

Follow these steps to set up notification relaying:

1. Create a new application
2. Add an endpoint for receiving notifications
3. Register the relay with Phenix's notification API

Step 1: Create Application

First, create an application with a secret key that will be used for authentication:

curl -X PUT https://notifications.phenixrts.app/applications \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "my-app-123",
    "secret": "your-secure-secret-key"
  }'

Expected response:

{
    "message": "Application added successfully",
    "applicationId": "my-app-123"
}

Step 2: Add Endpoint

Next, register the webhook endpoint where you want to receive notifications. Use Basic Authentication with your application credentials:

curl -X PUT https://notifications.phenixrts.app/my-app-123/endpoints \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'my-app-123:your-secure-secret-key' | base64)" \
  -d '{
    "url": "https://your-webhook-endpoint.com/notifications"
  }'

Expected response:

{
    "message": "Endpoint added",
    "endpoint": "https://your-webhook-endpoint.com/notifications"
}

Step 3: Register with Phenix

Finally, register the relay service URL with Phenix's notification API. The relay URL will be: https://notifications.phenixrts.app/{applicationId}/notifications

curl -X PUT https://pcast.phenixrts.com/pcast/application/my-app-123/callback \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'my-app-123:your-phenix-secret' | base64)" \
  -d '{
    "callback": {
      "protocol": "https",
      "host": "notifications.phenixrts.app",
      "port": 443,
      "method": "POST",
      "path": "/my-app-123/notifications"
    }
  }'

Expected response:

{
    "status": "ok",
    "endpoint": "POST https://notifications.phenixrts.app:443/my-app-123/notifications"
}

Verifying Setup

1. List your applications:

   curl -X GET https://notifications.phenixrts.app/applications

2. Check your registered endpoints:

   curl -X GET https://notifications.phenixrts.app/my-app-123/endpoints \
     -H "Authorization: Basic $(echo -n 'my-app-123:your-secure-secret-key' | base64)"

Authentication

• All endpoints support CORS
• Most endpoints use HTTP Basic Authentication with your application credentials
• Initial application creation is the only endpoint that requires credentials in the request body
• All requests should include Content-Type: application/json
• Basic Authentication should be formatted as:
  • Username: Your application ID
  • Password: Your application secret
• Credentials are used for:
  1. Validating incoming notifications from Phenix
  2. Authenticating application and endpoint management operations
  3. Generating new authentication headers when relaying to endpoints

Example Authentication Header

Authorization: Basic base64(applicationId:secret)

Application Management

Create Application

Creates a new application with an associated secret for HMAC authentication. This is the only endpoint that requires credentials in the request body.

PUT /applications
Content-Type: application/json

{
    "applicationId": "your-application-id",
    "secret": "your-secret-key"
}

Parameters:

• applicationId (required): Unique identifier for your application
• secret (required): Secret key used for HMAC authentication. This same secret will be used to:
  1. Validate incoming notifications from Phenix
  2. Generate new authentication headers when relaying to endpoints
  3. Authenticate management operations for this application

Response:

{
    "message": "Application added successfully",
    "applicationId": "your-application-id"
}

Status Codes:

• 201: Application created successfully
• 400: Invalid request parameters
• 409: Application already exists
• 500: Server error

Endpoint Management

Add Endpoint

Adds a webhook endpoint for a specific application. Requires Basic Authentication.

PUT /{applicationId}/endpoints
Authorization: Basic base64(applicationId:secret)
Content-Type: application/json

{
    "url": "https://your-webhook-endpoint.com/path"
}

Parameters:

• url (required): Valid HTTPS URL where notifications will be sent

Response:

{
    "message": "Endpoint added",
    "endpoint": "https://your-webhook-endpoint.com/path"
}

Status Codes:

• 201: Endpoint created successfully
• 400: Missing or invalid URL
• 401: Invalid credentials
• 409: Endpoint already exists
• 500: Server error

Security Considerations

• Always use HTTPS for all API calls
• Keep your application secret secure and never share it
• Rotate your application secret periodically
• Monitor the endpoint history for any unauthorized access attempts
• Use strong, unique secrets for each application
• Validate all notification signatures at your endpoints
• Consider implementing rate limiting at your endpoints

Troubleshooting

Common Issues

1. Authentication Failures
   • Double-check your application ID and secret
   • Ensure you're using Basic Authentication correctly
   • Verify the Base64 encoding of your credentials
2. Endpoint Registration Failures
   • Verify your endpoint URL is accessible
   • Ensure your endpoint URL starts with https://
   • Check that your endpoint can handle POST requests
3. Notification Not Received
   • Check the endpoint history for delivery status
   • Verify your endpoint is responding with 2XX status codes
   • Ensure your endpoint can validate HMAC signatures

Debugging Tools

1. Use the GET /applications endpoint to verify your application exists
2. Use the GET /{applicationId}/endpoints endpoint to check endpoint registration and history
3. Consider using webhook.site for testing endpoint delivery