Skip to main content

Webhooks

Webhooks allow your backend systems to receive real-time notifications about events occurring within PlaySafe, particularly when moderation actions are triggered by your Action Policies.

For example, when PlaySafe automatically applies a 10-day voice chat ban to a toxic user based on your policy, a webhook event can be sent to your server.

This enables you to implement custom logic in your own systems based on these events. PlaySafe sends detailed information about the event, allowing you to take appropriate actions within your game's ecosystem (e.g., updating a player's status in your database, logging the event in your own analytics, notifying community managers).

Webhooks are delivered as HTTP POST requests to an endpoint URL that you configure.

You can view and manage your webhook configurations from the PlaySafe dashboard.

How to Integrate Webhooks​

Prerequisites​

  • An Action Policy must be created and enabled in your PlaySafe dashboard.
  • The Action Policy must be configured to trigger actions (e.g., timeouts, mutes).
  • You need a server endpoint (URL) capable of receiving HTTP POST requests with a JSON payload.

Integration Steps​

  1. Configure Webhook URL in PlaySafe Dashboard:

    • Log in to your PlaySafe Dashboard.
    • Navigate to the Settings > Webhooks page (or similar section).
    • Click the "Add Webhook URL" (or equivalent) button.
    • Enter the public URL of your server endpoint that will listen for webhook events.
    • Save the configuration.

  2. Understand the Webhook Request Format: Webhook events will be sent as HTTP POST requests to your configured URL. The request body will contain a JSON payload with the following structure:

    interface WebhookPayload {
      /** ISO 8601 date string (YYYY-MM-DDTHH:mm:ss.sssZ) representing when the action ends */
      endDate: string;
      /** Name of the policy that triggered the action */
      trigger: string;
      /** URL to the audio file that triggered the action (if applicable, may be empty or null) */
      audioUrl: string | null;
      /** UUID of the product (your application) */
      productId: string;
      /** Transcribed text from the audio (if applicable, may be empty or null) */
      transcript: string | null;
      /** The specific violation detected - This corresponds to the 'Action Value' you configured in the PlaySafe policy */
      actionValue: string;
      /** Human-readable description of the action taken */
      description: string;
      /** ID of the player the action is taken against */
      playerUserId: string;
      /** Delay in seconds before the action takes effect (0 for immediate) */
      delayInSeconds: number;
      /** Duration of the action in minutes */
      durationInMinutes: number;
      /** Human-readable name of the action (e.g., 'Temporary Voice Ban') */
      actionFriendlyName: string;
    }

  3. Implement Your Endpoint Logic: Your server endpoint should be designed to:

    • Receive the POST request.
    • Validate the request (optional but recommended, e.g., check for a secret header if you configure one).
    • Parse the JSON payload.
    • Process the event data according to your game's logic. Examples:
      • Update the player's status in your game database (e.g., set isVoiceMuted = true, store muteExpiryDate = endDate).
      • Log the event to your internal monitoring or analytics systems.
      • Notify administrators or community managers.
    • Respond with an appropriate HTTP status code (e.g., 200 OK or 204 No Content) to acknowledge receipt. If PlaySafe doesn't receive a success response, it might retry sending the webhook.

Example Webhook Payload​

{
  "endDate": "2025-01-29T09:31:07.469Z",
  "trigger": "Toxicity Policy - High Severity",
  "audioUrl": "https://storage.example.com/audio-clips/clip-xyz.wav",
  "productId": "your-product-uuid",
  "transcript": "Go kill yourself you idiot!",
  "actionValue": "Severe Harassment",
  "description": "Player received a 1 hour voice ban for severe harassment.",
  "playerUserId": "player-789",
  "delayInSeconds": 0,
  "durationInMinutes": 60,
  "actionFriendlyName": "1 Hour Voice Ban"
}

By integrating webhooks, you can create a seamless connection between PlaySafe's automated moderation actions and your game's backend systems.