## Create or Update Subscription

Create a new subscription or replace your existing one. This operation is idempotent, the request body fully describes the desired subscription state, so any events not included in the request are removed.

**API Call Sample:**

```shell curl
curl -i -X PUT \
  -u '<username>:<password>' \
  https://asia.stage.rubyplay.io/api/v1/subscriptions/game-action-events \
  -H 'Content-Type: application/json' \
  -d '{
    "gameActionEvents": [
      {
        "name": "FEATURE",
        "gameId": "rp_140"
      }
    ],
    "callbackUrl": "https://callback-url.com/rubyplay",
    "auth": {
      "type": "BEARER",
      "apiKey": "5qohcMV9s2lakKzdQTJXfDr74Zz13yTsFe414eZLR86SW2o5kxbWGtg4m12FVbEo"
    }
  }'
```

```json 200 application/json
{
  "gameActionEvents": [
    {
      "name": "FEATURE",
      "gameId": "rp_140"
    }
  ],
  "callbackUrl": "https://callback-url.com/rubyplay",
  "auth": {
    "type": "BEARER",
    "credentialsConfigured": true
  }
}
```

```json 401 application/json
{
  "code": "NOT_AUTHORIZED",
  "message": "Authentication failed",
  "timestamp": "2026-01-25T14:30:00Z",
  "path": "/api/v1/subscriptions/game-action-events"
}
```

```json 403 application/json
{
  "code": "INSUFFICIENT_SCOPE",
  "message": "Insufficient scope to access this resource. Required: subscription:put",
  "timestamp": "2026-01-25T14:30:00Z",
  "path": "/api/v1/subscriptions/game-action-events"
}
```

```json 500 application/json
{
  "code": "UNKNOWN_ERROR",
  "message": "Something went wrong",
  "timestamp": "2026-01-25T14:30:00Z",
  "path": "/api/v1/subscriptions/game-action-events"
}
```

```json 504 application/json
{
  "code": "TIMEOUT",
  "message": "The server did not respond within the expected time",
  "timestamp": "2026-01-25T14:30:00Z",
  "path": "/api/v1/subscriptions/game-action-events"
}
```

**Request Schema:**

```json
{
  "$ref": "#/components/schemas/GameActionEventsSubscriptionUpdateDto",
  "components": {
    "schemas": {
      "GameActionEventDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Game Action Event name",
            "example": "FEATURE",
            "minLength": 1
          },
          "gameId": {
            "type": "string",
            "description": "Game ID.",
            "example": "rp_140",
            "minLength": 1
          }
        },
        "required": [
          "gameId",
          "name"
        ]
      },
      "GameActionEventsAuthUpdateDto": {
        "type": "object",
        "description": "Authentication configuration for webhook callbacks.\n\n**Authentication Types:**\n- **BEARER**: Use API key in Authorization header\n- **BASIC**: Use username/password with HTTP Basic auth\n- **NONE**: No authentication (not recommended for production)\n\n**Field Requirements by Type:**\n- BEARER: requires `apiKey`, forbids `username`/`password`\n- BASIC: requires `username` AND `password`, forbids `apiKey`\n- NONE: forbids all credential fields\n",
        "properties": {
          "type": {
            "type": "string",
            "description": "Type of auth for the webhook URL.",
            "enum": [
              "BEARER",
              "BASIC",
              "NONE"
            ],
            "example": "BEARER",
            "minLength": 1
          },
          "apiKey": {
            "type": "string",
            "description": "API key for the webhook URL, required if the type BEARER is chosen.",
            "example": "5qohcMV9s2lakKzdQTJXfDr74Zz13yTsFe414eZLR86SW2o5kxbWGtg4m12FVbEo"
          },
          "username": {
            "type": "string",
            "description": "Username for the webhook URL, required if the type BASIC is chosen.",
            "example": "rubyplay"
          },
          "password": {
            "type": "string",
            "description": "Password for the webhook URL, required if the type BASIC is chosen.",
            "example": "RTw1o3BgqPRvgoqbEuyMJkpwwMFPEv1c"
          }
        },
        "required": [
          "type"
        ]
      },
      "GameActionEventsSubscriptionUpdateDto": {
        "type": "object",
        "properties": {
          "gameActionEvents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GameActionEventDto",
              "description": "Game Action Events"
            },
            "minItems": 1
          },
          "callbackUrl": {
            "type": "string",
            "description": "Two options available:\n- Option 1: Omit both callbackUrl and auth - uses default endpoint `$wallet_url/v1/game-action-events` with existing wallet authentication\n- Option 2: Provide both callbackUrl and auth - uses custom webhook URL with custom authentication\n",
            "example": "https://callback-url.com/rubyplay"
          },
          "auth": {
            "$ref": "#/components/schemas/GameActionEventsAuthUpdateDto",
            "description": "Authentication for the webhook URL, which is specified in the callbackUrl field.\nThe field must be set if and only if the callbackUrl field is specified."
          }
        },
        "required": [
          "gameActionEvents"
        ]
      }
    }
  }
}
```

**Response Schema:**

```json
{
  "$ref": "#/components/schemas/GameActionEventsSubscriptionDto",
  "components": {
    "schemas": {
      "GameActionEventDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Game Action Event name",
            "example": "FEATURE",
            "minLength": 1
          },
          "gameId": {
            "type": "string",
            "description": "Game ID.",
            "example": "rp_140",
            "minLength": 1
          }
        },
        "required": [
          "gameId",
          "name"
        ]
      },
      "GameActionEventsAuthDto": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Type of auth for the webhook URL.",
            "enum": [
              "BEARER",
              "BASIC",
              "NONE"
            ],
            "example": "BEARER",
            "minLength": 1
          },
          "credentialsConfigured": {
            "type": "boolean",
            "description": "Credentials for auth type BASIC or BEARER are configured.",
            "example": true
          }
        },
        "required": [
          "credentialsConfigured",
          "type"
        ]
      },
      "GameActionEventsSubscriptionDto": {
        "type": "object",
        "properties": {
          "gameActionEvents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GameActionEventDto",
              "description": "Game Action Events"
            },
            "minItems": 1
          },
          "callbackUrl": {
            "type": "string",
            "description": "When this parameter is specified, it overrides the webhook URL.\nOtherwise, the default URL, which is used for money transactions, will be used (with the same auth type and credentials).",
            "example": "https://callback-url.com/rubyplay"
          },
          "auth": {
            "$ref": "#/components/schemas/GameActionEventsAuthDto",
            "description": "Authentication for the webhook URL, which is specified in the callbackUrl parameter"
          }
        },
        "required": [
          "gameActionEvents"
        ]
      }
    }
  }
}
```