Core Requirements

Performance Requirements

Response Time Limits

• Maximum: 500ms for all webhook endpoints
• Recommended: Under 100ms for optimal user experience
• Timeout: Phoenix retries up to 100 times with exponential backoff

Optimization Strategies

• Use indexed columns for player ID lookups
• Implement connection pooling and caching
• Minimize external API calls during webhook processing
• Deploy close to your database

Database & Transactions

Transaction Integrity

• Use database transactions for all balance-affecting operations
• Implement proper rollback mechanisms
• Ensure atomicity - all operations succeed or all fail
• Handle concurrent requests with row-level locking

Idempotency Implementation

• Store transaction IDs (tx_id, action_id) to prevent duplicate processing
• Return same response for duplicate requests
• Check if transaction exists before processing
• Maintain complete transaction log

Example Implementation

BEGIN TRANSACTION;
SELECT balance FROM players WHERE id = ? FOR UPDATE;
UPDATE players SET balance = balance - ? WHERE id = ?;
INSERT INTO transactions (player_id, amount, type, tx_id) VALUES (?, ?, ?, ?);
COMMIT;

Error Handling

HTTP Status Codes

• 200 OK - Successful operations
• 400 Bad Request - Invalid input
• 500 Internal Server Error - Server issues
• 503 Service Unavailable - Temporary outages

Error Response Format

{
  "type": "ERROR",
  "balance": 1234.56,
  "code": "INSUFFICIENT_BALANCE"
}

Standard Error Codes

• INSUFFICIENT_BALANCE - Not enough funds
• INVALID_REQUEST - Malformed request data
• PLAYER_NOT_FOUND - Unknown player ID
• DUPLICATE_TRANSACTION - Transaction already processed
• SYSTEM_ERROR - Internal server error

Currency & Amount Handling

Critical Rules

• All amounts are in cents - divide by 100 for actual value
• Use proper decimal arithmetic to avoid floating-point errors
• Always validate currency matches player account
• Validate amount ranges against game instance configuration

Example

// CORRECT
const withdrawAmount = request.amount / 100; // 5000 cents = $50
const newBalance = (balanceInCents - amountInCents) / 100;

Security Requirements

Signature Verification

• Always verify RSA signatures, even in dev/staging
• Use proper RSA verification with SHA-256
• Never trust requests without valid signatures
• Never log signatures or private keys

Credential Management

• Use environment variables for secrets
• Implement proper secret management
• Rotate keys regularly
• Never hardcode credentials in application code