Event System
🎉 Event System
The PrevNames API features a robust event system that allows you to stream real-time name change events. This page explains how to listen for and send name change events using the provided API endpoints.
Real-Time Name Change Events
The event system in PrevNames allows you to receive notifications whenever a user changes their username or display name in Discord. These events are sent over a Server-Sent Events (SSE) stream, allowing clients to receive updates as soon as they happen.
How It Works
Webhooks for Real-Time Events: When a user’s name (either username or display name) changes, the API broadcasts the change event to all active listeners who have connected to the stream.
GET /api/webhooks/prevnames/listen: This endpoint is used by clients to listen to real-time name change events.
POST /api/webhooks/prevnames: This endpoint is used to send name change events to all connected clients.
1. Listen for Events
Endpoint
GET /api/webhooks/prevnames/listenDescription
To listen for real-time name change events, make a GET request to this endpoint. This opens an SSE connection that keeps the client updated with any new name change events in real time.
How to Use
To receive events, your client should make a GET request to /api/webhooks/prevnames/listen. When a name change occurs, the server sends the event as follows:
data: {
"userId": "123456789012345678",
"type": "username",
"name": "NewUsername",
"changedAt": "2024-12-07T08:15:00Z"
}Each event is sent as a data field, which contains information about the name change.
Response Format
Once connected, the server will push new events in this format:
data: {
"userId": "123456789012345678",
"type": "username",
"name": "NewUsername",
"changedAt": "2024-12-07T08:15:00Z"
}userId: The Discord user ID of the user whose name has changed.type: The type of name change (usernameordisplayname).name: The previous name (either username or display name).changedAt: The timestamp when the name change occurred.
When Will Events Be Sent?
Events will be sent whenever the following happens:
A username change is detected for a user.
A display name change is detected for a user within a specific server.
Error Handling
If the connection is closed or there is an issue with the SSE stream, the event listener will stop receiving data. If there’s an error, you will need to handle it on the client side.
2. Send Name Change Events
Endpoint
POST /api/webhooks/prevnamesDescription
This endpoint allows you to send a name change event to all connected listeners. It is typically used when a name change event occurs (either from a bot or from an internal process) and you want to broadcast the change to all active listeners.
Request Body Example
To notify listeners of a new name change, you would send a POST request with the following JSON structure:
{
"userId": "123456789012345678",
"type": "username",
"name": "NewUsername",
"changedAt": "2024-12-07T08:15:00Z"
}userId: The Discord User ID of the user who changed their name.type: The type of name change (usernameordisplayname).name: The new name (either username or display name).changedAt: The timestamp of the name change.
Response Example
Once the event is successfully delivered to all active listeners, the API will respond with:
{
"success": true
}This confirms that the name change event has been successfully broadcasted to all connected clients.
Error Handling
If the event cannot be delivered (e.g., no listeners are connected), the response will include an error message:
{
"message": "Failed to deliver event.",
"code": 500
}3. Use Cases for the Event System
The event system is designed for a variety of use cases, including:
Discord Bot Integration: You can integrate this event system with a Discord bot to track user name changes in real time.
Server Monitoring: Track username and display name changes across different servers and notify administrators.
Analytics and Reporting: Collect data on name changes for analytics purposes, such as identifying name change patterns or trends.
4. Example of Full Flow
A user changes their username in Discord.
The API detects the name change and sends the event to all active listeners via the
/api/webhooks/prevnames/listenstream.A listener (client) receives the event and processes it (e.g., logs the change, notifies users, etc.).
If you need to broadcast a name change, use the
POST /api/webhooks/prevnamesendpoint to notify all listeners.
Example Flow in Code
// Start listening for events
const eventSource = new EventSource('http://discprev.xyz/api/webhooks/prevnames/listen');
eventSource.onmessage = (event) => {
const prevNameData = JSON.parse(event.data);
console.log('Received Name Change Event:', prevNameData);
};
// Send a name change event
fetch('http://discprev.xyz/api/webhooks/prevnames', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
userId: '123456789012345678',
type: 'username',
name: 'NewUsername',
changedAt: '2024-12-07T08:15:00Z'
})
})
.then(response => response.json())
.then(data => {
if (data.success) {
console.log('Event broadcasted successfully');
}
});Summary
The PrevNames Event System provides real-time streaming of name changes for Discord users. By using the GET /api/webhooks/prevnames/listen endpoint, clients can receive live notifications of name changes, and with POST /api/webhooks/prevnames, you can broadcast new events to all connected listeners. This allows for seamless integration into applications that need to track user name changes across Discord.
Last updated