Skip to main content
The Events API allows you to dispatch custom events to guilds, triggering Luau script execution within the Template Worker environment.

​
Event Dispatching

Dispatch a custom event to a guild and receive the execution results. This allows you to trigger custom Luau scripts and receive their output. Endpoint: POST /guilds/{guild_id}/events
Dispatch Event
curl -X POST https://splashtail-staging.antiraid.xyz/guilds/123456789012345678/events \
  -H "Authorization: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "WebCustomAction",
    "data": {
      "Text": "Hello from the API!"
    }
  }'
​
guild_id
string
required
The Discord ID of the guild to dispatch the event to
​
name
string
required
The event name. Must start with “Web” for security reasons.
​
data
KhronosValue
required
The event data to pass to the Luau script. Can be any valid KhronosValue type.

​
KhronosValue Types

The data field accepts various types of values. Here are the available KhronosValue types:

​
Simple Types

Text
{
  "name": "WebExample",
  "data": {
    "Text": "Hello, World!"
  }
}
Integer
{
  "name": "WebExample",
  "data": {
    "Integer": 42
  }
}
Float
{
  "name": "WebExample",
  "data": {
    "Float": 3.14159
  }
}
Boolean
{
  "name": "WebExample",
  "data": {
    "Boolean": true
  }
}
Null
{
  "name": "WebExample",
  "data": "Null"
}

​
Complex Types

List (Array)
{
  "name": "WebExample",
  "data": {
    "List": [
      {"Text": "first"},
      {"Integer": 2},
      {"Boolean": true}
    ]
  }
}
Map (Object)
{
  "name": "WebExample",
  "data": {
    "Map": [
      [{"Text": "key1"}, {"Text": "value1"}],
      [{"Text": "key2"}, {"Integer": 42}]
    ]
  }
}
LazyStringMap (Simple Object)
{
  "name": "WebExample",
  "data": {
    "LazyStringMap": {
      "action": "update",
      "target": "user_settings"
    }
  }
}

​
Special Types

Timestamptz (DateTime)
{
  "name": "WebExample",
  "data": {
    "Timestamptz": "2026-02-28T12:00:00Z"
  }
}
Buffer (Bytes)
{
  "name": "WebExample",
  "data": {
    "Buffer": [72, 101, 108, 108, 111]
  }
}
Vector (3D Coordinates)
{
  "name": "WebExample",
  "data": {
    "Vector": [1.0, 2.5, 3.7]
  }
}

​
Response

The API returns the result of the Luau script execution as a KhronosValue. 
{
  "Text": "Action completed successfully"
}
The response format depends on what your Luau script returns. It will always be a valid KhronosValue type.

​
Event Name Restrictions

For security reasons, all event names dispatched through the public API must start with “Web”.
  • ✅ Valid: WebCustomAction, WebUserUpdate, WebDataSync
  • ❌ Invalid: CustomAction, UserUpdate, InternalEvent
This restriction ensures that only web-safe events can be triggered externally.

​
Example Use Cases

​
Trigger a Custom Action

User Action
curl -X POST https://splashtail-staging.antiraid.xyz/guilds/123456789012345678/events \
  -H "Authorization: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "WebUserAction",
    "data": {
      "LazyStringMap": {
        "action": "vote",
        "option": "yes"
      }
    }
  }'

​
Pass Structured Data

Complex Event
curl -X POST https://splashtail-staging.antiraid.xyz/guilds/123456789012345678/events \
  -H "Authorization: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "WebFormSubmit",
    "data": {
      "Map": [
        [{"Text": "username"}, {"Text": "john_doe"}],
        [{"Text": "age"}, {"Integer": 25}],
        [{"Text": "verified"}, {"Boolean": true}],
        [{"Text": "tags"}, {
          "List": [
            {"Text": "developer"},
            {"Text": "contributor"}
          ]
        }]
      ]
    }
  }'

​
Error Handling

{
  "message": "Event name must start with 'Web' for security reasons",
  "code": "Forbidden"
}

​
Best Practices

  • Always validate event names before sending (ensure they start with “Web”)
  • Handle execution errors gracefully - scripts may timeout or fail
  • Keep event data payloads reasonably sized
  • Use LazyStringMap for simple key-value data instead of complex Map structures
  • Test your Luau scripts thoroughly before deploying to production

​
Luau Script Integration

To handle custom events in your guild, you’ll need to set up Luau scripts that listen for your custom event names. The event data you send will be available in the Luau script’s event handler. Example Luau script:
Event Handler Example
-- Listen for WebCustomAction events
function onWebCustomAction(event)
    local message = event.data.Text or "No message"
    
    -- Process the event
    print("Received message: " .. message)
    
    -- Return a response
    return {
        Text = "Action completed: " .. message
    }
end
Refer to the Template Worker Luau documentation for more details on writing event handlers.

Build docs developers (and LLMs) love

Get started for freeTalk to us