Callback Payload Format

Reference for the JSON payload sent to your server callback endpoint

Payload Structure

VotePipe sends vote data as a JSON object in the request body:

json

{
  "event": "vote",
  "vote_id": "vt_550e8400-e29b-41d4-a716-446655440000",
  "voter_name": "PlayerName",
  "provider": "hytale-servers-pro",
  "received_at": "2026-01-02T15:30:00.123Z"
}

Field Descriptions

Field	Type	Description
event	string	Always "vote" for vote events
vote_id	string	Unique identifier for this vote (format: `vt_` + UUID)
voter_name	string	The player's username who voted
provider	string	The provider key (e.g., "hytale-servers-pro", "hytalecharts")
received_at	string	ISO 8601 timestamp when VotePipe received the vote

Example Implementation

Here's a simple example of how to handle the callback in different languages:

Node.js / Express

javascript

app.post('/api/vote', async (req, res) => {
  const { event, vote_id, voter_name, provider, received_at } = req.body;
  
  // Verify authentication header if configured
  const authHeader = req.headers.authorization;
  if (authHeader !== `Bearer ${process.env.CALLBACK_SECRET}`) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  
  // Process the vote
  await giveReward(voter_name);
  
  res.json({ success: true });
});

Python / Flask

python

@app.route('/api/vote', methods=['POST'])
def handle_vote():
    data = request.json
    voter_name = data['voter_name']
    
    # Verify authentication
    auth_header = request.headers.get('Authorization')
    if auth_header != f"Bearer {os.getenv('CALLBACK_SECRET')}":
        return jsonify({'error': 'Unauthorized'}), 401
    
    # Process the vote
    give_reward(voter_name)
    
    return jsonify({'success': True})

Response Format

Your endpoint should return a JSON response:

json

{
  "success": true
}

Any 2xx status code is considered successful. 4xx and 5xx codes will trigger retries.

Learn More

→ Callback Setup → Retry Logic → Troubleshooting